feat(spm): manifest+plugin watch paths, artifact version pinning, template warning

Three staleness/robustness hardening items:

1. Watch-path staleness (closes three gaps): the sync phase's
   .spm-sync-watch-paths file now carries mixed dirs AND files. Each
   autolinked npm dep's checked-in root Package.swift and .react-native/
   dir are watched (dep root threaded from the autolinking model), so
   editing a library manifest finally trips the in-build re-sync (file
   edits never bump parent-dir mtimes, so the old dirs-only watch missed
   them). Plugins gain a watchPaths contract (absolute dirs/files,
   validated warn-and-drop like flavoredArtifacts) so plugin packages
   contribute staleness inputs. A watched path that VANISHES now forces
   a re-sync so the autolinker surfaces the real config error instead of
   dangling-symlink noise. The generated phase loop distinguishes
   -d (find -newer probe) / -f ([ -nt ]) / vanished (stale). Behavioral
   sh tests drive the real generated loop under /bin/sh.

2. Artifact version pinning: an explicit `spm add/update --version <v>`
   is recorded as artifactsVersionOverride in .spm-injected.json
   (preserved on later runs without --version; removed by deinit), and
   the in-build sync prefers it over the package.json-derived version —
   previously a version-mismatched setup had every in-build sync heal
   against the wrong artifact slot. findInjectedXcodeproj moved to
   generate-spm-xcodeproj.js as the single marker-lookup authority.

3. installSpmCodegenTemplate warns loudly when the SPM codegen template
   file is missing (previously a silent no-op that left codegen's
   mis-rooted default Package.swift breaking every subsequent Resolve
   Package Graph).

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

Author: chrfalch

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

@@ -88,9 +88,9 @@ const {
 const {main: generatePackage} = require('./spm/generate-spm-package');
 const {findSourcePath} = require('./spm/generate-spm-package');
 const {
-  SPM_INJECTED_MARKER,
   cleanupDanglingJavaScriptCoreRef,
   cleanupLeftoverPodsGroup,
+  findInjectedXcodeproj,
   injectSpmIntoExistingXcodeproj,
   removeSpmInjection,
 } = require('./spm/generate-spm-xcodeproj');
@@ -884,6 +884,11 @@ async function setupXcodeproj(
     reactNativeRoot,
     xcodeprojPath,
     appName: args.productName,
+    // Only an EXPLICIT `--version` pins the artifacts-cache slot in the
+    // marker; omitting it (null) leaves any previously-recorded pin alone
+    // (injectSpmIntoExistingXcodeproj preserves it — see
+    // generate-spm-xcodeproj.js).
+    artifactsVersionOverride: args.version ?? null,
   });
   if (result.status !== 'injected') {
     logError(`SPM injection failed: ${result.reason}`);
@@ -903,28 +908,6 @@ async function setupXcodeproj(
   }
 }
 
-// Returns the `*.xcodeproj` carrying a `.spm-injected.json` marker (the
-// user-owned project SPM packages were injected into in place), else null.
-function findInjectedXcodeproj(appRoot /*: string */) /*: string | null */ {
-  let entries /*: Array<{name: string, isDirectory(): boolean}> */;
-  try {
-    // $FlowFixMe[incompatible-type] Dirent typing
-    entries = fs.readdirSync(appRoot, {withFileTypes: true});
-  } catch {
-    return null;
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    // $FlowFixMe[incompatible-type] Dirent.name is string|Buffer in Flow stubs
-    const name /*: string */ = entry.name;
-    if (!name.endsWith('.xcodeproj')) continue;
-    if (fs.existsSync(path.join(appRoot, name, SPM_INJECTED_MARKER))) {
-      return path.join(appRoot, name);
-    }
-  }
-  return null;
-}
-
 // True when `git status --porcelain` reports the path dirty/untracked. Returns
 // null when git is unavailable or the path is outside a repo (no safety net).
 function gitTrackedAndClean(

packages/react-native/scripts/spm/__doc__/spm-autolinking-plugins.md

@@ -92,6 +92,12 @@ module.exports = function plugin(context) {
         },
       },
     ],
+    watchPaths: [
+      // Inputs whose edits must re-trigger the auto-sync — the plugin's own
+      // manifest and per-module config (absolute paths, dirs or files):
+      '/…/node_modules/expo/Package.swift',
+      '/…/node_modules/expo/expo-module.config.json',
+    ],
   };
 };
 ```
@@ -119,6 +125,23 @@ plugin links in the same pass as RN's own frameworks. Because that repoint runs
 in the scheme pre-action, plugin artifacts inherit graph-time embed correctness
 for free — no plugin-side swap script needed.
 
+#### `watchPaths` — plugin staleness inputs
+
+`watchPaths` is an array of **absolute** paths (dirs **or** files) the Xcode
+auto-sync build phase watches to decide whether it must re-sync. RN already
+watches each module's source dir plus every npm dep's checked-in `Package.swift`
+and `.react-native/` dir; a plugin adds the inputs only it knows about — e.g.
+`packages/expo/Package.swift`, `expo-module.config.json`, and per-module
+manifests. On the next build the phase re-syncs when a watched **file** is newer
+than the last sync, a watched **dir** has a newer child, or a watched path has
+**vanished** (a rename forces a re-sync so the config error surfaces).
+
+Validation mirrors `flavoredArtifacts`: a non-array is ignored with a warning
+(never fatal), and each non-string / empty / **relative** entry is dropped with a
+warning. Absolute-only, because the generated phase tests these paths with no cwd
+context. The kept paths are folded into `<outputDir>/.spm-sync-watch-paths`
+alongside RN's own, then deduped and sorted.
+
 ### Context (input)
 
 | Field | Meaning |

packages/react-native/scripts/spm/__tests__/autolinking-plugins-test.js

@@ -307,4 +307,64 @@ describe('invokePlugins', () => {
       true,
     );
   });
+
+  it('keeps valid absolute watchPaths (dirs or files) across plugins', () => {
+    const res = invokePlugins(
+      [
+        mk('expo', () => ({
+          watchPaths: [
+            '/app/node_modules/expo/Package.swift',
+            '/app/node_modules/expo/expo-module.config.json',
+          ],
+        })),
+        mk('b', () => ({watchPaths: ['/app/node_modules/b']})),
+      ],
+      ctx,
+    );
+    expect(res.watchPaths).toEqual([
+      '/app/node_modules/expo/Package.swift',
+      '/app/node_modules/expo/expo-module.config.json',
+      '/app/node_modules/b',
+    ]);
+  });
+
+  it('defaults watchPaths to [] when no plugin declares any', () => {
+    const res = invokePlugins([mk('a', () => ({}))], ctx);
+    expect(res.watchPaths).toEqual([]);
+  });
+
+  it('drops relative / empty / non-string watchPaths with a per-entry warning', () => {
+    const warnings = [];
+    const res = invokePlugins(
+      [
+        mk('expo', () => ({
+          watchPaths: [
+            '/app/node_modules/expo/Package.swift', // kept
+            'relative/Package.swift', // relative → dropped
+            '', // empty → dropped
+            42, // non-string → dropped
+          ],
+        })),
+      ],
+      ctx,
+      {warn: m => warnings.push(m)},
+    );
+    expect(res.watchPaths).toEqual(['/app/node_modules/expo/Package.swift']);
+    expect(warnings).toHaveLength(3);
+    expect(warnings.every(w => /invalid watchPath/.test(w))).toBe(true);
+  });
+
+  it('ignores a non-array watchPaths with a warning (never throws)', () => {
+    const warnings = [];
+    let res;
+    expect(() => {
+      res = invokePlugins(
+        [mk('expo', () => ({watchPaths: '/app/x'}))], // string, not array
+        ctx,
+        {warn: m => warnings.push(m)},
+      );
+    }).not.toThrow();
+    expect(res.watchPaths).toEqual([]);
+    expect(warnings.some(w => /non-array watchPaths/.test(w))).toBe(true);
+  });
 });

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

@@ -1250,3 +1250,126 @@ describe('main() — flavoredArtifacts sidecar', () => {
     ]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// main() — .spm-sync-watch-paths emission (mixed dirs + files)
+//
+// The watch file drives the Xcode auto-sync stale check. It must carry, mixed
+// and deduped/sorted: (1) each module's source DIR; (2) each npm dep's
+// checked-in root Package.swift (FILE) and .react-native/ (DIR) — threaded from
+// the autolinking model's dep root, not derived by walking up; (3) plugin
+// watchPaths. Nonexistent paths are filtered at emission time.
+// ---------------------------------------------------------------------------
+
+describe('main() — .spm-sync-watch-paths emission', () => {
+  let created = [];
+  let spies = [];
+
+  beforeEach(() => {
+    for (const m of ['log', 'warn', 'error']) {
+      spies.push(jest.spyOn(console, m).mockImplementation(() => {}));
+    }
+  });
+  afterEach(() => {
+    for (const s of spies) s.mockRestore();
+    spies = [];
+    for (const d of created) fs.rmSync(d, {recursive: true, force: true});
+    created = [];
+  });
+
+  function readWatchLines(appRoot) {
+    const contents = fs.readFileSync(
+      path.join(appRoot, 'build/generated/autolinking/.spm-sync-watch-paths'),
+      'utf8',
+    );
+    return contents.split('\n').filter(l => l.length > 0);
+  }
+
+  it('emits source dirs + dep manifests + .react-native dirs + plugin paths, deduped and sorted', () => {
+    // realpath so paths derived here match a plugin's realpath'd __dirname
+    // (macOS /var → /private/var symlink).
+    const appRoot = fs.realpathSync(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'spm-watch-emit-')),
+    );
+    created.push(appRoot);
+    const rnRoot = path.join(appRoot, 'rn');
+    fs.mkdirSync(rnRoot, {recursive: true});
+    fs.writeFileSync(
+      path.join(appRoot, 'package.json'),
+      JSON.stringify({name: 'app'}),
+    );
+
+    // (B) A self-managed community dep: root Package.swift (no AUTOGEN marker)
+    // makes it self-managed; it also ships a .react-native/ metadata dir.
+    const fooDir = path.join(appRoot, 'node_modules', 'react-native-foo');
+    fs.mkdirSync(fooDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(fooDir, 'Package.swift'),
+      '// swift-tools-version:5.9\n// hand-authored\n',
+    );
+    fs.mkdirSync(path.join(fooDir, '.react-native'));
+    fs.writeFileSync(path.join(fooDir, '.react-native', 'meta.json'), '{}\n');
+    fs.writeFileSync(path.join(fooDir, 'Foo.swift'), '// src\n');
+
+    // (C) A plugin-host dep contributing watchPaths: one existing absolute path
+    // (kept), one absent absolute path (filtered at emission), one relative
+    // path (dropped by invokePlugins).
+    const expoDir = path.join(appRoot, 'node_modules', 'expo');
+    fs.mkdirSync(path.join(expoDir, 'ios'), {recursive: true});
+    fs.writeFileSync(path.join(expoDir, 'ios', 'Expo.mm'), '// native\n');
+    fs.writeFileSync(path.join(expoDir, 'Package.swift'), '// expo manifest\n');
+    fs.writeFileSync(
+      path.join(expoDir, 'react-native.config.js'),
+      "module.exports = { spm: { autolinkingPlugin: './spm-plugin.js' } };\n",
+    );
+    fs.writeFileSync(
+      path.join(expoDir, 'spm-plugin.js'),
+      [
+        "const path = require('path');",
+        'module.exports = function () {',
+        '  return {',
+        "    packageDependencies: [{name: 'ExpoModulesCore', path: '../../../../node_modules/expo/ios'}],",
+        "    productDependencies: [{name: 'ExpoModulesCore', package: 'ExpoModulesCore'}],",
+        '    watchPaths: [',
+        "      path.join(__dirname, 'Package.swift'),", // exists → kept
+        "      path.join(__dirname, 'MISSING.swift'),", // absent → filtered at emission
+        "      'rel/manifest',", // relative → dropped by invokePlugins
+        '    ],',
+        '  };',
+        '};',
+      ].join('\n') + '\n',
+    );
+
+    const autolinkDir = path.join(appRoot, 'build', 'generated', 'autolinking');
+    fs.mkdirSync(autolinkDir, {recursive: true});
+    fs.writeFileSync(
+      path.join(autolinkDir, 'autolinking.json'),
+      JSON.stringify({
+        dependencies: {
+          'react-native-foo': {root: fooDir, platforms: {ios: {}}},
+          expo: {root: expoDir, platforms: {ios: {}}},
+        },
+      }),
+    );
+
+    main(['--app-root', appRoot, '--react-native-root', rnRoot]);
+
+    const lines = readWatchLines(appRoot);
+
+    // (A/B) foo's source dir, root manifest FILE, and .react-native DIR.
+    expect(lines).toContain(fooDir);
+    expect(lines).toContain(path.join(fooDir, 'Package.swift'));
+    expect(lines).toContain(path.join(fooDir, '.react-native'));
+
+    // (C) plugin's existing absolute watchPath is kept.
+    expect(lines).toContain(path.join(expoDir, 'Package.swift'));
+
+    // Filtered / dropped entries never reach the file.
+    expect(lines.some(l => l.includes('MISSING.swift'))).toBe(false);
+    expect(lines.some(l => l.includes('rel/manifest'))).toBe(false);
+
+    // Deduped and sorted (stable, deterministic output).
+    expect(new Set(lines).size).toBe(lines.length);
+    expect([...lines].sort()).toEqual(lines);
+  });
+});