feat(apple): Refactor Xcode project primitives for snapshots

[cameroncooke]

Stack

This is 1/3 in the Apple Snapshots stack replacing the original unified PR #1293.

• 1/3: feat(apple): Refactor Xcode project primitives for snapshots #1295 — Xcode project primitives (this PR)
• 2/3: feat(apple): Add interactive Apple Snapshots wizard #1296 — Interactive Apple Snapshots wizard
• 3/3: feat(apple): Add non-interactive Apple Snapshots mode #1297 — Non-interactive Apple Snapshots mode

The top of the stack is intended to be an exact, lossless re-expression of #1293.

Summary

This PR refactors the existing Apple/Xcode project infrastructure needed by the Apple Snapshots wizard, without exposing the new appleSnapshots wizard yet.

The goal is to make the shared Xcode helpers reviewable independently before adding the user-facing SnapshotPreviews flow. Existing Sentry Apple setup remains routed through the current ios wizard; this layer should be shared infrastructure, not a new runtime setup behavior.

What changed

• Split Xcode project lookup/selection helpers so target discovery can be reused by the snapshots flow.
• Move Sentry Swift package metadata into a reusable package spec.
• Extend XcodeProject with reusable helpers for:
  • hosted XCTest target detection via TEST_HOST
  • app bundle ID / executable lookup
  • Swift package product linking
  • source file resolution
  • Swift source insertion
  • synchronized-folder source membership support
• Preserve existing configureXcodeProject / updateXcodeProject behavior for the normal Apple SDK setup path.
• Add focused tests for the refactored project lookup, Xcode mutation, and git helper behavior.

What this PR intentionally does not do

• Does not add the appleSnapshots integration option.
• Does not add the Apple Snapshots wizard entrypoint.
• Does not configure SnapshotPreviews yet.
• Does not configure Sentry auth, DSNs, runtime SDK initialization, dSYM upload scripts, Fastlane setup, MCP config, or CI workflow files.

Those pieces land in the upstack PRs.

Suggested review focus

• .pbxproj mutation correctness and idempotency.
• Shared Swift package product linking behavior.
• Hosted XCTest target detection via TEST_HOST.
• Ensuring existing ios wizard behavior did not accidentally change.
• Whether the helper boundaries are general enough for both normal Apple SDK setup and SnapshotPreviews setup.

Risk

Medium. This refactors shared Apple/Xcode project mutation code used by existing setup paths. The risk is primarily around unusual Xcode project graphs, package product linking, target discovery, and source membership handling.

Validation

Before submitting the stack:

• yarn test passed: 947 passed, 4 skipped
• yarn build passed
• Final stack tree matched original PR feat(apple): Add Apple Snapshots wizard #1293 exactly
• gt submit --stack --dry-run passed

Co-Authored-By: GPT-5 Codex noreply@openai.com

[cameroncooke]

• feat(apple): Add non-interactive Apple Snapshots mode #1297
• feat(apple): Add interactive Apple Snapshots wizard #1296
• feat(apple): Refactor Xcode project primitives for snapshots #1295 👈 (View in Graphite)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Bundle ID picks first config
  • The function now resolves build setting macros using resolveBuildSettingValue and prefers Release configuration over Debug to return the correct bundle identifier.

Or push these changes by commenting:

@cursor push 64690a7812

Preview (64690a7812)

diff --git a/src/apple/xcode-manager.ts b/src/apple/xcode-manager.ts
--- a/src/apple/xcode-manager.ts
+++ b/src/apple/xcode-manager.ts
@@ -304,11 +304,48 @@
       return undefined;
     }
 
-    return this.getTargetBuildSettings(target.obj)
-      .map((buildSettings) => {
-        return unquote(buildSettings.PRODUCT_BUNDLE_IDENTIFIER);
-      })
-      .find(Boolean);
+    const buildConfigurationListId = target.obj.buildConfigurationList;
+    if (!buildConfigurationListId) {
+      return undefined;
+    }
+
+    const configurationList = this.objects.XCConfigurationList?.[
+      buildConfigurationListId
+    ] as XCConfigurationList | undefined;
+    if (!configurationList || typeof configurationList === 'string') {
+      return undefined;
+    }
+
+    const configurations = configurationList.buildConfigurations ?? [];
+    let releaseBundleId: string | undefined;
+    let fallbackBundleId: string | undefined;
+
+    for (const configRef of configurations) {
+      const config = this.objects.XCBuildConfiguration?.[configRef.value];
+      if (!config || typeof config === 'string') {
+        continue;
+      }
+
+      const bundleId = resolveBuildSettingValue(
+        config.buildSettings?.PRODUCT_BUNDLE_IDENTIFIER,
+        target.obj.name,
+      );
+      if (!bundleId) {
+        continue;
+      }
+
+      if (!fallbackBundleId) {
+        fallbackBundleId = bundleId;
+      }
+
+      const configName = unquote(config.name).toLowerCase();
+      if (configName.includes('release')) {
+        releaseBundleId = bundleId;
+        break;
+      }
+    }
+
+    return releaseBundleId ?? fallbackBundleId;
   }
 
   /**

_{You can send follow-ups to the cloud agent here.}

[itaybre]

Almost LGTM, mainly the v8 is blocking here

[itaybre]

m: This might be personal preference, but feels like this source file grew a lot and could be broken into a couple files (SPM logic, types and all the utilities).
But I am sure this would also break the stacked PRs :(

[cameroncooke]

I'll address this as a separate PR if that's okay.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Variable TEST_HOST breaks hosted detection
  • Modified testHostReferencesApplication to detect TEST_HOST values using Xcode macros like $(WRAPPER_NAME) and $(EXECUTABLE_NAME) in addition to literal names.

Or push these changes by commenting:

@cursor push c178b88ddf

Preview (c178b88ddf)

diff --git a/src/apple/xcode-manager.ts b/src/apple/xcode-manager.ts
--- a/src/apple/xcode-manager.ts
+++ b/src/apple/xcode-manager.ts
@@ -89,13 +89,32 @@
   const referencesAppBundle = appHostCandidates.bundleNames.some((bundleName) =>
     containsPathSegment(resolvedTestHost, `${bundleName}.app`),
   );
-  if (!referencesAppBundle) {
-    return false;
+  const referencesExecutable = appHostCandidates.executableNames.some(
+    (executableName) => containsPathSegment(resolvedTestHost, executableName),
+  );
+
+  if (referencesAppBundle && referencesExecutable) {
+    return true;
   }
 
-  return appHostCandidates.executableNames.some((executableName) =>
-    containsPathSegment(resolvedTestHost, executableName),
+  const hasBundleMacro =
+    /\$\(WRAPPER_NAME\)|\$\(PRODUCT_NAME\)/.test(resolvedTestHost) ||
+    (resolvedTestHost.includes('.app') &&
+      /\$\(FULL_PRODUCT_NAME\)/.test(resolvedTestHost));
+  const hasExecutableMacro = /\$\(EXECUTABLE_NAME\)|\$\(PRODUCT_NAME\)/.test(
+    resolvedTestHost,
   );
+
+  if (
+    hasBundleMacro &&
+    hasExecutableMacro &&
+    appHostCandidates.bundleNames.length > 0 &&
+    appHostCandidates.executableNames.length > 0
+  ) {
+    return true;
+  }
+
+  return false;
 }
 
 function containsPathSegment(value: string, segment: string): boolean {

diff --git a/test/apple/xcode-manager.test.ts b/test/apple/xcode-manager.test.ts
--- a/test/apple/xcode-manager.test.ts
+++ b/test/apple/xcode-manager.test.ts
@@ -203,6 +203,122 @@
       });
     });
 
+    describe('getHostedUnitTestTargetNamesForApplicationTarget', () => {
+      let xcodeProject: XcodeProject;
+      let tempPbxprojPath: string;
+
+      beforeEach(() => {
+        const tempDir = fs.mkdtempSync(
+          path.join(os.tmpdir(), 'xcode-test-hosted-unit-tests-'),
+        );
+        const xcodeprojDir = path.join(tempDir, 'Project.xcodeproj');
+        fs.mkdirSync(xcodeprojDir, { recursive: true });
+        fs.mkdirSync(path.join(tempDir, 'Sources'), { recursive: true });
+        tempPbxprojPath = path.join(xcodeprojDir, 'project.pbxproj');
+        fs.copyFileSync(singleTargetProjectPath, tempPbxprojPath);
+        xcodeProject = new XcodeProject(tempPbxprojPath);
+      });
+
+      it('should find hosted unit test with literal app and executable names in TEST_HOST', () => {
+        // -- Arrange --
+        addHostedUnitTestTarget(xcodeProject, {
+          name: 'ProjectTests',
+          hostAppName: 'Project',
+          projectObjectId,
+          productsGroupId,
+        });
+
+        // -- Act --
+        const hostedTests =
+          xcodeProject.getHostedUnitTestTargetNamesForApplicationTarget(
+            'Project',
+          );
+
+        // -- Assert --
+        expect(hostedTests).toEqual(['ProjectTests']);
+      });
+
+      it('should find hosted unit test with macro-based TEST_HOST', () => {
+        // -- Arrange --
+        addHostedUnitTestTarget(xcodeProject, {
+          name: 'ProjectMacroTests',
+          hostAppName: 'Project',
+          testHost:
+            '"$(BUILT_PRODUCTS_DIR)/$(WRAPPER_NAME)/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/$(EXECUTABLE_NAME)"',
+          projectObjectId,
+          productsGroupId,
+        });
+
+        // -- Act --
+        const hostedTests =
+          xcodeProject.getHostedUnitTestTargetNamesForApplicationTarget(
+            'Project',
+          );
+
+        // -- Assert --
+        expect(hostedTests).toEqual(['ProjectMacroTests']);
+      });
+
+      it('should find multiple hosted unit tests with different TEST_HOST formats', () => {
+        // -- Arrange --
+        addHostedUnitTestTarget(xcodeProject, {
+          name: 'ProjectLiteralTests',
+          hostAppName: 'Project',
+          projectObjectId,
+          productsGroupId,
+        });
+        addHostedUnitTestTarget(xcodeProject, {
+          name: 'ProjectMacroTests',
+          hostAppName: 'Project',
+          testHost:
+            '"$(BUILT_PRODUCTS_DIR)/$(WRAPPER_NAME)/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/$(EXECUTABLE_NAME)"',
+          projectObjectId,
+          productsGroupId,
+        });
+
+        // -- Act --
+        const hostedTests =
+          xcodeProject.getHostedUnitTestTargetNamesForApplicationTarget(
+            'Project',
+          );
+
+        // -- Assert --
+        expect(hostedTests).toContain('ProjectLiteralTests');
+        expect(hostedTests).toContain('ProjectMacroTests');
+        expect(hostedTests).toHaveLength(2);
+      });
+
+      it('should not find unit tests with wrong app name in TEST_HOST', () => {
+        // -- Arrange --
+        addHostedUnitTestTarget(xcodeProject, {
+          name: 'OtherAppTests',
+          hostAppName: 'OtherApp',
+          projectObjectId,
+          productsGroupId,
+        });
+
+        // -- Act --
+        const hostedTests =
+          xcodeProject.getHostedUnitTestTargetNamesForApplicationTarget(
+            'Project',
+          );
+
+        // -- Assert --
+        expect(hostedTests).toEqual([]);
+      });
+
+      it('should return empty array when app target does not exist', () => {
+        // -- Act --
+        const hostedTests =
+          xcodeProject.getHostedUnitTestTargetNamesForApplicationTarget(
+            'NonExistentTarget',
+          );
+
+        // -- Assert --
+        expect(hostedTests).toEqual([]);
+      });
+    });
+
     describe('ensureSwiftPackageProductLinked', () => {
       let xcodeProject: XcodeProject;

_{You can send follow-ups to the cloud agent here.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 9b38d1e. Configure here.}

[philprime]

LGTM

[philprime]

l: please inline this constant

[cameroncooke]

@cursor fix

[cursor]

I've fixed the review comment by inlining the sentrySwiftPackageProductLinkOptions constant.

The change:

• Removed the swiftPackageProduct variable declaration on line 690
• Replaced all 7 usages of swiftPackageProduct with the constant sentrySwiftPackageProductLinkOptions directly in the test calls

Tests pass and the code has been formatted. Changes committed and pushed to the branch.

  

[sentry]

Bug: The function shouldUpdatePackageRequirement incorrectly triggers an update when requirement kinds differ, causing it to silently overwrite a user's manually configured Swift Package requirement with the wizard's default.
_{Severity: LOW}

Suggested Fix

Modify shouldUpdatePackageRequirement to handle differing kind properties more gracefully. Instead of returning true and causing an overwrite, consider returning false to preserve the user's configuration and logging a warning that the existing requirement type is different from the wizard's default.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: src/apple/xcode-manager.ts#L379-L381

Potential issue: The `shouldUpdatePackageRequirement` function returns `true` if an
existing Swift Package requirement has a different `kind` than the one requested by the
wizard. This causes the calling function, `ensureSwiftPackageReference`, to overwrite
the user's entire requirement object. If a user has manually configured their Sentry
package with a specific requirement kind, such as `exactVersion`, running the wizard
will silently replace it with the default `upToNextMajorVersion` kind. This overwrites a
user's explicit configuration without their consent, although the scenario is unlikely
in practice.

[cameroncooke]

Merge activity

• Jul 1, 4:39 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 1, 4:39 PM UTC: @cameroncooke merged this pull request with Graphite.