fix(spm): delete the embedded-flavor phase; hard-fail + converge on flavor flips

The appended `Fix SPM Embedded Flavor` phase raced Xcode's standalone
CodeSign of the same frameworks (no dependency edge exists: declaring the
.app paths as phase outputs collides with the implicit embed's outputs —
"Multiple commands produce" — and declaring the SOURCE paths cycles
through the package targets). Instrumented builds further proved the
implicit embed is unordered with respect to script phases entirely, and
that scheme pre-actions race graph capture non-deterministically: no
in-build mechanism can affect what the current build embeds. Only the
state at build start counts.

New semantics — hard-fail + converge:
- The appended phase is gone (and is actively removed from already-
  injected projects on `spm add`/`update`). React Native writes nothing
  into the .app; Xcode's own embed copies and signs the pinned flavor.
- A build that STARTS with the wrong pinned flavor corrects the symlinks
  and BUILT_PRODUCTS copies, completes the sync, then deliberately fails:
  "frameworks were pinned to 'debug' but this is a Release build — they
  have been switched; build again." The rebuild is green with the correct
  flavor linked AND embedded. Exactly one explanatory red build per
  configuration flip; a stale-flavor binary can never ship silently.
- Only the LEADING swap may flag the failure (it alone observes the
  start state); a trailing correction converges silently, so mid-build
  re-syncs and fresh-clone auto-heals never produce a false red.
- The scheme pre-action is now sync-only: a pre-action swap that won its
  race would mask a mismatched start into a false green.
- `npx react-native spm update --flavor <x>` remains the zero-red-build
  way to switch ahead of time.

E2E-verified on a real app with code signing enabled, both directions:
matched builds green; flips red with the message and a converged pin;
rebuilds green with the correct embedded flavor (nm-verified) and valid
signatures; stale re-syncs on a matched pin stay green.

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

Author: chrfalch

packages/react-native/scripts/setup-apple-spm.js

@@ -996,27 +996,37 @@ async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
   // Build-time flavor swap (invoked by the generated build phase). Kept early
   // and dependency-free — no version resolution, no network — because it runs
   // on EVERY Xcode build. Reads the Xcode build env for the target flavor +
-  // products dir.
+  // products dir. It ONLY repoints the app-local slot symlinks + corrects the
+  // link-step product copies — it NEVER writes the embedded `.app/Frameworks`
+  // copy (Xcode is that bundle's single writer).
   if (action === 'swap-flavor') {
     const {swapFlavorFrameworks} = require('./spm/swap-flavor');
     try {
-      swapFlavorFrameworks({
+      const result = swapFlavorFrameworks({
         appRoot,
         configuration: process.env.CONFIGURATION,
         builtProductsDir: process.env.BUILT_PRODUCTS_DIR,
         platformName: process.env.PLATFORM_NAME,
         isMacCatalyst: process.env.IS_MACCATALYST === 'YES',
-        // Embedded-copy correction (the appended "Fix SPM Embedded Flavor"
-        // phase runs after Xcode's implicit SPM Embed). Absent in the scheme
-        // pre-action, so the embedded fix is a no-op there.
-        targetBuildDir: process.env.TARGET_BUILD_DIR,
-        frameworksFolderPath: process.env.FRAMEWORKS_FOLDER_PATH,
-        codeSigningAllowed: process.env.CODE_SIGNING_ALLOWED,
-        expandedCodeSignIdentity: process.env.EXPANDED_CODE_SIGN_IDENTITY,
         logger: {log},
       });
+      // HARD-FAIL + CONVERGE. When an IN-TARGET build (BUILT_PRODUCTS_DIR set,
+      // i.e. hasProducts) STARTED on the wrong flavor and we just repointed it,
+      // this build must still fail: Xcode captured the stale embed source at
+      // graph-construction time, before this phase ran, and that cannot be fixed
+      // in-place (a second .app writer races Xcode's CodeSign). The pin is now
+      // correct, so the REBUILD is green. The generated build phase propagates
+      // this exit 1 to fail the build (at the END, after the trailing swap). No
+      // hard-fail in the pre-action (hasProducts false) — it stays auto-heal.
+      if (result.hasProducts && result.builtinsCorrected) {
+        const cfg = process.env.CONFIGURATION ?? '(unknown)';
+        logError(
+          `error: React Native SwiftPM frameworks were pinned to '${result.previousFlavor}' but this is a ${cfg} build. They have been switched to ${result.flavor} — build again (one-time after a configuration change). Tip: 'npx react-native spm update --flavor ${result.flavor}' switches ahead of time.`,
+        );
+        process.exitCode = 1;
+      }
     } catch (e) {
-      // Non-fatal: a flavor-swap failure must not break the build.
+      // Non-fatal: a genuine flavor-swap failure must not break the build.
       logError(`swap-flavor failed: ${e.message}`);
     }
     return;

packages/react-native/scripts/spm/__tests__/generate-spm-xcodeproj-test.js

@@ -12,7 +12,7 @@
 
 const {
   addPreActionToScheme,
-  buildEmbeddedFixScript,
+  buildSchemePreActionScript,
   buildSyncAutolinkingScript,
   generateXcscheme,
 } = require('../generate-spm-xcodeproj');
@@ -303,14 +303,20 @@ describe('buildSyncAutolinkingScript', () => {
     expect(script).not.toContain('[[');
   });
 
-  it('is deterministic — the build phase and scheme pre-action get the same single script', () => {
-    // injectSpmPackages builds the phase with buildSyncAutolinkingScript(rnPath)
-    // and the scheme pre-action with the same call; a pure, deterministic result
-    // guarantees both embed byte-identical text.
+  it('is deterministic (pure) — repeated calls are byte-identical', () => {
     expect(buildSyncAutolinkingScript(BAKED)).toBe(
       buildSyncAutolinkingScript(BAKED),
     );
   });
+
+  it('the in-target phase and the scheme pre-action are now DIFFERENT scripts', () => {
+    // The phase carries the swap sandwich; the pre-action is sync-only. A
+    // pre-action swap could win its race and mask a mismatch from the in-target
+    // detector (a false green), so they intentionally diverge.
+    expect(buildSyncAutolinkingScript(BAKED)).not.toBe(
+      buildSchemePreActionScript(BAKED),
+    );
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -412,38 +418,186 @@ describe('buildSyncAutolinkingScript watch-paths stale loop (behavioral)', () =>
 });
 
 // ---------------------------------------------------------------------------
-// buildEmbeddedFixScript — the appended in-target phase that runs AFTER Xcode's
-// implicit SPM Embed to deterministically correct the embedded framework flavor.
+// The obsolete appended "Fix SPM Embedded Flavor" phase is gone entirely — RN
+// never writes the .app bundle (Xcode is its single writer).
 // ---------------------------------------------------------------------------
-describe('buildEmbeddedFixScript', () => {
-  const BAKED = '../node_modules/react-native';
-  const script = buildEmbeddedFixScript(BAKED);
+describe('embedded-fix phase removal', () => {
+  it('no longer exports buildEmbeddedFixScript', () => {
+    expect(require('../generate-spm-xcodeproj').buildEmbeddedFixScript).toBe(
+      undefined,
+    );
+  });
 
-  it('shares the node/RN_DIR resolution preamble with the sync script', () => {
-    expect(script).toContain('NODE_BINARY="${NODE_BINARY:-}"');
+  it('no script references the embedded-fix phase', () => {
+    const BAKED = '../node_modules/react-native';
+    for (const s of [
+      buildSyncAutolinkingScript(BAKED),
+      buildSchemePreActionScript(BAKED),
+    ]) {
+      expect(s).not.toContain('Fix SPM Embedded Flavor');
+      expect(s).not.toContain('SPM embedded-flavor fix could not run');
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// HARD-FAIL + CONVERGE — the in-target phase runs the swap sandwich and fails
+// the build ONCE at the end after correcting a mismatched start; the scheme
+// PRE-ACTION is sync-only (no swap → cannot mask a mismatch = false green).
+// ---------------------------------------------------------------------------
+describe('buildSchemePreActionScript (sync-only)', () => {
+  const script = buildSchemePreActionScript('../node_modules/react-native');
+
+  it('does NOT dispatch or define a flavor swap', () => {
+    expect(script).not.toContain('swap-flavor');
+    expect(script).not.toContain('run_swap_flavor');
+    expect(script).not.toContain('MISMATCH');
+  });
+
+  it('still runs the sync dispatch (its auto-heal purpose)', () => {
     expect(script).toContain(
-      "require('path').dirname(require.resolve('react-native/package.json'))",
+      '"$NODE_BINARY" "$RN_DIR/scripts/setup-apple-spm.js" sync',
     );
-    expect(script).toContain(`RN_DIR="${BAKED}"`);
+    expect(script).toContain('if [ "$STALE" -eq 1 ]; then');
   });
 
-  it('dispatches swap-flavor directly (no npx) and is a single dispatch (no sync, no sandwich)', () => {
-    expect(script).toContain(
-      '"$NODE_BINARY" "$RN_DIR/scripts/setup-apple-spm.js" swap-flavor',
+  it('parses under `sh -n`', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'preaction-'));
+    const file = path.join(dir, 'pre.sh');
+    fs.writeFileSync(file, script);
+    try {
+      expect(() => execFileSync('/bin/sh', ['-n', file])).not.toThrow();
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  });
+});
+
+describe('buildSyncAutolinkingScript — swap sandwich + hard-fail', () => {
+  const script = buildSyncAutolinkingScript('../node_modules/react-native');
+
+  it('runs the swap sandwich (def + leading + trailing = ≥3 run_swap_flavor uses)', () => {
+    expect(
+      (script.match(/run_swap_flavor/g) || []).length,
+    ).toBeGreaterThanOrEqual(3);
+  });
+
+  it('the LEADING swap runs BEFORE the sync dispatch (state corrected up front)', () => {
+    const leading = script.indexOf('run_swap_flavor\n');
+    const sync = script.indexOf('setup-apple-spm.js" sync');
+    expect(leading).toBeGreaterThan(-1);
+    expect(leading).toBeLessThan(sync);
+  });
+
+  it('captures the corrected-mismatch signal and defers the failure to the END', () => {
+    expect(script).toContain('MISMATCH_PENDING');
+    const gate = script.indexOf('if [ "$MISMATCH_PENDING" -eq 1 ]');
+    expect(gate).toBeGreaterThan(-1);
+    // The failure gate is AFTER the last swap (trailing) and after sync.
+    expect(gate).toBeGreaterThan(script.lastIndexOf('run_swap_flavor'));
+    expect(script.indexOf('setup-apple-spm.js" sync')).toBeLessThan(gate);
+    expect(script.indexOf('exit 1', gate)).toBeGreaterThan(gate);
+  });
+
+  it('parses under `sh -n`', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'phase-'));
+    const file = path.join(dir, 'phase.sh');
+    fs.writeFileSync(file, script);
+    try {
+      expect(() => execFileSync('/bin/sh', ['-n', file])).not.toThrow();
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  });
+});
+
+// A real-shell behavioral check of HARD-FAIL + CONVERGE. The stub setup-apple-spm
+// is STATEFUL: swap-flavor reads a fake pin file, and only repoints + exits 1 on
+// a genuine pin-vs-CONFIGURATION mismatch; sync re-pins the fake pin to debug
+// (modelling generate-spm-package's default-debug links). This exercises the
+// leading-vs-trailing distinction the constant-exit-code stub could not.
+describe('sync script — shell behavior of HARD-FAIL + CONVERGE', () => {
+  let dir, rnDir, srcroot, pinFile;
+
+  function setup(startFlavor) {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'shell-hardfail-'));
+    srcroot = path.join(dir, 'app');
+    fs.mkdirSync(srcroot, {recursive: true});
+    fs.writeFileSync(
+      path.join(srcroot, 'package.json'),
+      JSON.stringify({name: 'x'}),
     );
-    // Exactly one swap dispatch; NOT the sync-phase machinery.
-    expect(script.match(/setup-apple-spm\.js" swap-flavor/g)).toHaveLength(1);
-    expect(script).not.toContain('swap-flavor" sync');
-    expect(script).not.toContain('run_swap_flavor');
-    expect(script).not.toContain('"$STALE"');
+    pinFile = path.join(dir, 'pin');
+    fs.writeFileSync(pinFile, startFlavor); // the flavor the build STARTS on
+    rnDir = path.join(dir, 'rn');
+    fs.mkdirSync(path.join(rnDir, 'scripts'), {recursive: true});
+    fs.writeFileSync(
+      path.join(rnDir, 'scripts', 'setup-apple-spm.js'),
+      [
+        "const fs = require('fs');",
+        'const pinFile = process.env.FAKE_PIN_FILE;',
+        'const a = process.argv[2];',
+        // sync re-pins to the add-time (debug) flavor, like linkOne does.
+        "if (a === 'sync') { fs.writeFileSync(pinFile, 'debug'); process.exit(0); }",
+        "if (a === 'swap-flavor') {",
+        "  const desired = process.env.CONFIGURATION === 'Release' ? 'release' : 'debug';",
+        "  const pin = fs.existsSync(pinFile) ? fs.readFileSync(pinFile, 'utf8').trim() : 'debug';",
+        '  if (pin !== desired) {',
+        '    fs.writeFileSync(pinFile, desired);',
+        "    console.log('error: corrected ' + pin + ' -> ' + desired);",
+        '    process.exit(1);',
+        '  }',
+        '  process.exit(0);',
+        '}',
+        'process.exit(0);',
+      ].join('\n'),
+    );
+    const scriptFile = path.join(dir, 'phase.sh');
+    fs.writeFileSync(scriptFile, buildSyncAutolinkingScript(rnDir));
+    return scriptFile;
+  }
+
+  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+  function run(scriptFile, configuration) {
+    try {
+      execFileSync('/bin/sh', [scriptFile], {
+        env: {
+          ...process.env,
+          SRCROOT: srcroot,
+          BUILT_PRODUCTS_DIR: path.join(dir, 'products'),
+          NODE_BINARY: process.execPath,
+          CONFIGURATION: configuration,
+          FAKE_PIN_FILE: pinFile,
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf8',
+      });
+      return {code: 0};
+    } catch (e) {
+      return {code: e.status, out: (e.stdout || '') + (e.stderr || '')};
+    }
+  }
+
+  it('SUCCEEDS (exit 0) when only the TRAILING swap repoints (sync re-pinned mid-build) — not a mismatched start', () => {
+    // Start on release, build Release: the LEADING swap is matched (no
+    // correction). The (stale) sync re-pins to debug, so the TRAILING swap
+    // repoints back to release. Only the leading swap may flag a mismatch, so
+    // this must NOT fail the build.
+    const {code} = run(setup('release'), 'Release');
+    expect(code).toBe(0);
   });
 
-  it('soft-fails (warns, no exit 1) so it never hard-breaks the build alone', () => {
-    expect(script).toContain('warning: SPM embedded-flavor fix could not run');
-    expect(script).not.toContain('exit 1');
+  it('FAILS the build (exit 1) when the build STARTED on the wrong flavor (leading swap corrects)', () => {
+    // Start on debug, build Release: the LEADING swap corrects debug->release and
+    // flags it → fail once, converge, rebuild green.
+    const {code, out} = run(setup('debug'), 'Release');
+    expect(code).toBe(1);
+    expect(out).toMatch(/error:/);
   });
 
-  it('is POSIX-sh clean (no bashisms)', () => {
-    expect(script).not.toContain('[[');
+  it('SUCCEEDS (exit 0) when the build started matched (Debug on debug)', () => {
+    const {code} = run(setup('debug'), 'Debug');
+    expect(code).toBe(0);
   });
 });

packages/react-native/scripts/spm/__tests__/inject-spm-xcodeproj-test.js

@@ -194,18 +194,53 @@ describe('injectSpmIntoPbxproj — Tier 2 (build settings + phase)', () => {
     expect(syncIdx).toBeLessThan(sourcesIdx);
   });
 
-  it('APPENDS the Fix SPM Embedded Flavor phase (last in buildPhases)', () => {
+  it('does NOT append a Fix SPM Embedded Flavor phase (RN never writes the .app)', () => {
     const {text} = inject(PLAIN);
-    expect(text).toContain('Fix SPM Embedded Flavor');
-    // Its buildPhases-array member is the LAST entry (appended, not prepended).
+    expect(text).not.toContain('Fix SPM Embedded Flavor');
     const bp = text.slice(text.indexOf('buildPhases = ('));
     const arr = bp.slice(0, bp.indexOf(');'));
     const comments = [...arr.matchAll(/\/\* ([^*]+) \*\//g)].map(m => m[1]);
     expect(comments[0]).toBe('Sync SPM Autolinking'); // prepended, first
-    expect(comments[comments.length - 1]).toBe('Fix SPM Embedded Flavor');
-    // Runs after Sources (post-embed).
-    const fixIdx = text.indexOf('Fix SPM Embedded Flavor */,');
-    expect(fixIdx).toBeGreaterThan(text.indexOf('Sources */,'));
+    expect(comments).not.toContain('Fix SPM Embedded Flavor');
+  });
+
+  it('MIGRATES away an existing Fix SPM Embedded Flavor phase on re-injection (object + membership)', () => {
+    const {namespacedUUID} = require('../spm-pbxproj');
+    const {text: first} = inject(PLAIN);
+    const plan = planInjection(PLAIN, {});
+    const legacyUuid = namespacedUUID(
+      plan.rootUuid,
+      'PBXShellScriptBuildPhase',
+      'FixEmbeddedFlavor',
+    );
+    // Splice a legacy phase object + its buildPhases membership back in, as an
+    // app injected by an older RN would have.
+    const withObject = first.replace(
+      '/* End PBXShellScriptBuildPhase section */',
+      `\t\t${legacyUuid} /* Fix SPM Embedded Flavor */ = {\n\t\t\tisa = PBXShellScriptBuildPhase;\n\t\t\tname = "Fix SPM Embedded Flavor";\n\t\t\tshellScript = "echo legacy";\n\t\t};\n/* End PBXShellScriptBuildPhase section */`,
+    );
+    const withLegacy = withObject.replace(
+      /(buildPhases = \([\s\S]*?)(\n\t\t\t\);)/,
+      `$1\n\t\t\t\t${legacyUuid} /* Fix SPM Embedded Flavor */,$2`,
+    );
+    expect(withLegacy).toContain('Fix SPM Embedded Flavor');
+
+    const plan2 = planInjection(withLegacy, {});
+    const {text: healed} = injectSpmIntoPbxproj(
+      withLegacy,
+      {
+        rootUuid: plan2.rootUuid,
+        targetUuid: plan2.target.uuid,
+        configUuids: plan2.configUuids,
+        frameworksPhaseUuid: plan2.frameworksPhaseUuid,
+        sourcesPhaseUuid: plan2.sourcesPhaseUuid,
+      },
+      RN_PATH,
+      null,
+    );
+    expect(healed).not.toContain('Fix SPM Embedded Flavor');
+    expect(healed).not.toContain(legacyUuid);
+    expect(isBalanced(healed)).toBe(true);
   });
 });
 
@@ -385,31 +420,6 @@ describe('injectSpmIntoPbxproj — invariants', () => {
     expect(second).toBe(first);
   });
 
-  it('refreshes a stale Fix SPM Embedded Flavor shellScript on re-injection', () => {
-    const first = inject(PLAIN).text;
-    // Corrupt a substring unique to the embedded-fix phase script.
-    const stale = first.replace(
-      'SPM embedded-flavor fix could not run',
-      'STALE_EMBEDDED_MARKER',
-    );
-    expect(stale).not.toBe(first);
-    const plan = planInjection(stale, {});
-    const second = injectSpmIntoPbxproj(
-      stale,
-      {
-        rootUuid: plan.rootUuid,
-        targetUuid: plan.target.uuid,
-        configUuids: plan.configUuids,
-        frameworksPhaseUuid: plan.frameworksPhaseUuid,
-      },
-      RN_PATH,
-      null,
-    ).text;
-    expect(second).not.toContain('STALE_EMBEDDED_MARKER');
-    expect(second).toContain('SPM embedded-flavor fix could not run');
-    expect(second).toBe(first);
-  });
-
   it('namespaces injected UUIDs by the host project root (collision-safe, stable)', () => {
     const {injectedUuids} = inject(PLAIN);
     // All injected UUIDs are valid 24-hex and none collide with the originals.