diff --git a/.github/workflows/drift-watch.yml b/.github/workflows/drift-watch.yml index 53c84a2..69269c8 100644 --- a/.github/workflows/drift-watch.yml +++ b/.github/workflows/drift-watch.yml @@ -3,7 +3,7 @@ # Daily (23 5 * * *): each supported line gets a fresh project (the newest patch of its line), and the project gates, # the bundled patches and the manifest rewrite are checked on it. Nothing is compiled: there is no Swift and no # Darwin SDK here. One `drift` issue is kept per broken line; it is closed when the line is green again. -# Weekly (47 5 * * 1): a report-only exploration of older lines (Expo SDK 54-56, bare React Native 0.81-0.84). It +# Weekly (47 5 * * 1): a report-only exploration of older lines (Expo SDK 54-55, bare React Native 0.81-0.84). It # writes a capability table to the run summary and opens no issue. # By hand: workflow_dispatch with mode `daily` or `explore`; `drill` (a line id, such as bare-0.88) marks that line # broken for one daily run, to test the issue path end to end. diff --git a/CHANGELOG.md b/CHANGELOG.md index df991eb..3c4857e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,8 +25,65 @@ versions follow [Semantic Versioning](https://semver.org/) with `alpha` prerelea and `doctor --project`: "The app target takes its files from the synchronized folder (an Xcode 16 folder group); rn-xtool reads only the files a target lists. Convert the folder to a group (Xcode: Convert to Group) so the target lists its files". +- Expo SDK 55 and older are refused with "Expo SDK is not supported; rn-xtool supports SDK 56 (expo 56.0.24 or + newer 56.x), SDK 57 (expo 57.0.31 or newer 57.x) and SDK 58 or newer.", and `doctor --project` gives them its + `support comes with the translator` reason; SDK 56 was among the refused SDKs before. +- On Expo SDK 58 (and 56), and in hybrid apps (bare React Native with Expo modules, SDK 58), the version check reads + expo-file-system and expo-font where expo-modules-autolinking links them, as its own CLI answers (`resolve --platform + apple --json`, the question the Expo plugin asks), instead of under `node_modules/expo` only: the app's own top-level + copy, a dependency's copy, a `file:`-linked library's copy and the folders `expo.autolinking` settings add are read as + the build links them. A package autolinking does not link is skipped when a copy is installed and the app excludes it + (`expo.autolinking.exclude`, or the `exclude` of `expo.autolinking.apple`, else of `expo.autolinking.ios`), and stops + the check when it is installed and not excluded: " is installed () but Expo's autolinking does not link + it for iOS, and the app does not exclude it: the build would succeed and the app would fail at launch with "Cannot + find native module". …". When that CLI cannot run (no answer within 20 seconds included), the check falls back to the + top-level copy when the app, or a package it lists, depends on it, else the copy under `expo`, and says so in one + line: "⚠ rn-xtool could not ask Expo's autolinking which expo-file-system and expo-font copies the build links + (), so it read their versions from node_modules: … The build asks autolinking again and may link another copy. + See …". See [troubleshooting.md](docs/troubleshooting.md#expo-sdk-58). +- The `jsi` step's missing-headers error names no React Native version: "ExpoModulesJSI needs React Native's headers + at , which does not exist. rnArtifactsDir must hold the adapted slots of the project's React Native version, as + rn-xtool's rn-artifacts step writes them." +- The vendored Expo plugin (SDK 56 and 57) gives each generated Expo package the highest of its `spm.config.json` + floor, the iOS deployment target its podspec declares and core's (edit P7), capped at the App target's iOS 16.4. A + module whose podspec asks for more prints, once after `rn-spm`, "⚠ 's podspec asks for iOS , and + rn-xtool builds the app for iOS 16.4, so is compiled for iOS 16.4: its code that needs iOS must + be behind an availability check (`if #available(iOS , *)`). On a Mac, the app's deployment target would be + raised to iOS instead." The SDK 57 reference app's packages stay at iOS 16.4. See + [vendor/expo-spm/README.md](vendor/expo-spm/README.md). +- The weekly drift exploration covers Expo SDK 54 and 55 (and bare React Native 0.81 to 0.84); SDK 56 moved to the + daily watch. ### Added +- Expo SDK 56 (expo 56.0.24 or newer 56.x, react-native 0.85.3), on SDK 57's route: the vendored Expo plugin, the + vendored React Native 0.88.0 scripts, React Native 0.85.3's adapted artifacts, and the `jsi` step before `rn-spm`. + Its set is a floor: at least expo 56.0.24, expo-modules-core 56.0.27, expo-modules-jsi 56.0.14, + expo-modules-autolinking 56.0.24, expo-file-system 56.0.11 and expo-font 56.0.7, each on SDK 56's line, with + react-native exactly 0.85.3. Below it the build stops with "Expo SDK 56 needs react-native 0.85.3 and at least expo + 56.0.24, … expo-font 56.0.7; installed: …" and the remedy; a newer 56.x builds with "⚠ Newer than the Expo SDK 56 set + this rn-xtool release was verified with: …". `doctor --project` reads `Expo SDK 56: expo 56.0.24 (verified + 56.0.24), react-native 0.85.3 (verified 0.85.3)`. Build-verified only: a fresh `default@sdk-56` template with + expo-dev-client builds (2026-11-11; 346 s cold, 65 s warm, `App.app` 140 MB with 14 frameworks, G4 passing), and SDK + 56 has not been run on a device yet. Known on the template: its `ios.icon` is an Icon Composer icon, so the app has + no icon until `ios.icon` is a PNG, and ExpoModulesWorkletsAdapter is left out because ExpoModulesCore is + precompiled. See [how-it-works.md](docs/how-it-works.md#expo-sdk-56). +- `expo-modules-jsi+56.0.14.patch`, staged on SDK 56 only (also for a newer 56.x jsi): `expo.CppError`'s `message` + made internal so Swift 6.4 compiles it, and four conformances to the internal `JSIRepresentable` marked + `@_spi(Internal)`, as jsi 57.1.3 does, so Swift 6.4 writes a readable ExpoModulesJSI interface. When it does not + apply, the stop names the SDK 56 `"overrides"` block. +- The `jsi` step takes `NativeState.h` from either expo-modules-jsi layout (`include/Public` on jsi 57 and newer, + `include` on jsi 56), with every header it includes with quotes. A missing one stops the step: "expo-modules-jsi + ships no NativeState.h (looked in /Public and ); cannot make + ExpoModulesJSIHeaders.xcframework." or "
of expo-modules-jsi includes "", which is not next + to it in ; cannot make ExpoModulesJSIHeaders.xcframework.". +- On Expo SDK 56 and 57 the `jsi` step reads the `ExpoModulesJSI.swiftinterface` it built and stops when an + `extension` line has an empty place in its list of protocols, which no Swift compiler parses: "The + ExpoModulesJSI.swiftinterface built for expo-modules-jsi () has lines no Swift compiler can + parse, for example line : . Every module that imports ExpoModulesJSI would fail to compile. …", naming + another Swift than 6.4 as the likely cause when it wrote the interface. Before, the build failed minutes later at + `xtool-build` with `expected type` errors. See + [troubleshooting.md](docs/troubleshooting.md#unreadable-expomodulesjsi-interface). +- The daily drift watch checks `expo-56/default` (`default@sdk-56`), and `-f drill=expo-56` drills it. - The `precheck` build step, between `generate` and `xtool-build`: SwiftPM plans the generated package, the app's includes are resolved again with the App target's full include list, `swiftc -typecheck` checks the Swift files and `clang -fsyntax-only` each C-family file with the generated manifest's flags. When a Swift file imports a module @@ -55,6 +112,24 @@ versions follow [Semantic Versioning](https://semver.org/) with `alpha` prerelea - `rn-xtool doctor --report` has a `precheck:` line: `precheck: run (last build)`, `precheck: skipped with --skip-precheck (last build)` or `precheck: not recorded`. +### Fixed +- A build interrupted during the `jsi` step (Ctrl-C, a closed terminal, a reboot) no longer breaks every later build, + `build --clean` included, with clang's "… .pcm' is not a valid module file". `build --clean` (and `run --clean`) + removes the jsi build's scratch, `ios-xtool/jsi-out/.jsi-build`, before the `jsi` step on every project that has one; + Expo's `expo prebuild --clean` leaves `ios-xtool` alone, so it stayed before. A `jsi` failure with that clang error + now adds "The jsi step stopped on a precompiled module file in ExpoModulesJSI's module cache that is empty or cut + short ("is not a valid module file"): a build interrupted during the jsi step leaves its module cache that way, and + the next builds keep reading it. Run `rm -rf ios-xtool/jsi-out/.jsi-build` in the project folder, then `rn-xtool + build`, or run `rn-xtool build --clean`, …". A build interrupted during `xtool-build` leaves the app build's module + cache, under `ios-xtool/.build`, the same way, and on Expo `build --clean` keeps that folder: an `xtool-build` failure + (at `build`, `install` or `install --network`) with that clang error now adds "xtool dev build stopped on a + precompiled module file in the app build's module cache (ios-xtool/.build) that is empty or cut short ("is not a valid + module file"): … Run `rm -rf ios-xtool/.build` in the project folder, then `rn-xtool build`: its xtool-build starts + cold and takes several minutes. …". A file clang names anywhere else gets no paragraph. The `jsi` and `xtool-build` + steps' output now goes through a pipe, so rn-xtool can read it: SwiftPM prints each progress update (`[n/m] Compiling + …`) on a line of its own instead of redrawing one line, and its errors without colour. See + [troubleshooting.md](docs/troubleshooting.md#interrupted-build). + ## [0.1.0-alpha.8] - 2026-11-09 ### Upgrading from 0.1.0-alpha.7 diff --git a/README.md b/README.md index 5460f38..8c78ca0 100644 --- a/README.md +++ b/README.md @@ -23,10 +23,11 @@ Demo video coming soon. | --- | --- | | Expo SDK 58 (expo 58.0.21 or newer 58.x, react-native 0.88.1) | ✅ [details](docs/how-it-works.md#expo-sdk-58) | | Expo SDK 57 (expo 57.0.31 or newer 57.x, react-native 0.86.3) | ✅ [details](docs/how-it-works.md#expo-sdk-57) | +| Expo SDK 56 (expo 56.0.24 or newer 56.x, react-native 0.85.3; build-verified only) | ✅ [details](docs/how-it-works.md#expo-sdk-56) | | Bare React Native 0.88.x from 0.88.0 (`@react-native-community/cli init`) | ✅ [details](docs/bare-react-native.md) | | Bare React Native 0.85.x from 0.85.0, 0.86.x from 0.86.2, 0.87.x from 0.87.1 (0.85.3 and 0.86.2 build-verified only) | ✅ [details](docs/bare-react-native.md#supported-react-native-versions) | | Bare React Native + Expo modules (hybrid), React Native 0.88.1 | ✅ [details](docs/bare-react-native.md#hybrid-bare--expo-modules) | -| Expo SDK 54–56, React Native 0.84 and older, 0.86.0, 0.86.1, 0.87.0 | ⏳ not yet (Expo SDK 53 and older are refused as well) | +| Expo SDK 54–55, React Native 0.84 and older, 0.86.0, 0.86.1, 0.87.0 | ⏳ not yet (Expo SDK 53 and older are refused as well) | | iOS simulator | ❌ macOS only | | Production / App Store builds | ❌ use EAS | | macOS or Windows as the host | ❌ (WSL2 on x86_64 should work as Linux; not tested yet, reports welcome) | @@ -36,9 +37,10 @@ Bare React Native versions: 0.85.x from 0.85.0, 0.86.x from 0.86.2, 0.87.x from run on a device), see [Supported React Native versions](docs/bare-react-native.md#supported-react-native-versions). A newer patch of one of these lines builds with a warning naming the verified versions. An older version, a prerelease or another minor stops -with one error naming these floors. Expo SDK 57 and 58 work the same way: newer patches of the SDK's packages build -with a warning, older ones stop, and react-native stays exact (0.86.3 on SDK 57, 0.88.1 on SDK 58) -([details](docs/troubleshooting.md#newer-than-the-verified-versions)). +with one error naming these floors. Expo SDK 56, 57 and 58 work the same way: newer patches of the SDK's packages +build with a warning, older ones stop, and react-native stays exact (0.85.3 on SDK 56, 0.86.3 on SDK 57, 0.88.1 on +SDK 58) ([details](docs/troubleshooting.md#newer-than-the-verified-versions)). Expo SDK 56 is build-verified only: a +fresh default template builds (2026-11-11), and it has not been run on a device yet. Apps that grew from older React Native templates build too: a production bare React Native 0.85.0 app with an Objective-C app target (`main.m`, `AppDelegate.h` and `AppDelegate.mm` next to the project, a bridging header and a @@ -155,7 +157,7 @@ Details, every message and what to do: [docs/troubleshooting.md](docs/troublesho | `setup [--xcode-xip ] [--wifi [--yes] [--udid ]]` | Installs Swift via swiftly, the xtool AppImage and the Darwin SDK. Idempotent. `--wifi` is the one-time USB step for Wi‑Fi installs: it caches the pair record and, with `--yes`, enables Wi‑Fi connections on the iPhone. | | `auth [args...]` | Runs `xtool auth ` (`auth login`, `auth logout`); with no arguments, `xtool auth status`. | | `doctor [--project] [--report]` | Checks toolchain, SDK, login, connected device, Wi‑Fi install readiness and project. Exits non-zero on problems. `--project` checks only the project in the current folder: its version gates, what rn-xtool finds in it and the setups it cannot build yet. `--report` prints the same checks as one block to paste into a GitHub issue, with your home folder, Apple ID, Team ID, bundle identifiers, UDIDs, device names, IP and MAC addresses replaced by placeholders, and makes no network request ([details](docs/troubleshooting.md#reporting-a-problem)). | -| `build [--clean] [--skip-precheck]` | Prebuild if `ios/` is missing (Expo only), patches, RN/Expo SwiftPM pipeline, ExpoModulesJSI (Expo modules only), generates `ios-xtool/`, checks the app's own sources (`precheck`), `xtool dev build`. `--clean` re-runs `expo prebuild --clean` for Expo; for bare it removes `ios/build` and `ios-xtool` and leaves the rest of `ios/` alone. `--skip-precheck` leaves the `precheck` step out, and the check of the app's own includes at build start warns instead of stopping ([details](docs/troubleshooting.md#precheck)). | +| `build [--clean] [--skip-precheck]` | Prebuild if `ios/` is missing (Expo only), patches, RN/Expo SwiftPM pipeline, ExpoModulesJSI (Expo modules only), generates `ios-xtool/`, checks the app's own sources (`precheck`), `xtool dev build`. `--clean` re-runs `expo prebuild --clean` for Expo; for bare it removes `ios/build` and `ios-xtool` and leaves the rest of `ios/` alone. On both, the `jsi` step builds ExpoModulesJSI again from an empty scratch folder (`ios-xtool/jsi-out/.jsi-build`). `--skip-precheck` leaves the `precheck` step out, and the check of the app's own includes at build start warns instead of stopping ([details](docs/troubleshooting.md#precheck)). | | `install [--network [ip] [--udid ] [--pair-record ]]` | Signs and installs the app on the USB-connected iPhone (over Wi‑Fi without the cable with `--network`, see [docs/wifi-install.md](docs/wifi-install.md)), then prints, for apps with expo-dev-client, the Metro URL with a link and QR code that open the app on it, and the first-run checklist. | | `start [--clear]` | Starts Metro (`npx expo start`; `npx react-native start` for bare) on the port and LAN IP the app was built for. Tells you to rebuild if either changed; clears the Metro cache when dependencies changed (or with `--clear`). With expo-dev-client it announces Metro to the dev launcher under the installed app's bundle id. | | `run [--clean] [--force] [--network [ip]] [--skip-precheck]` | `build` and `install` when dependencies changed (or with `--force`), then `start`. `--network` installs over Wi‑Fi; `--skip-precheck` goes to `build`. | diff --git a/docs/README.md b/docs/README.md index f36fff6..a2de263 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,15 +6,15 @@ Wi‑Fi installs, troubleshooting, library compatibility, and the research and d ## Guides - [how-it-works.md](how-it-works.md): what `setup` installs, the bundled patches, the build steps, how the SwiftPM - scripts are chosen, the Expo SDK 58 and 57 version floors and the precompiled framework check (G4), Expo SDK 57 - through the vendored Expo SwiftPM plugin, the first-launch reload helper, dev-client discovery, mixed-language + scripts are chosen, the Expo SDK 58, 57 and 56 version floors and the precompiled framework check (G4), Expo SDK 57 + and 56 through the vendored Expo SwiftPM plugin, the first-launch reload helper, dev-client discovery, mixed-language manifests, CocoaPods-only libraries and reference timings. - [bare-react-native.md](bare-react-native.md): bare React Native projects (0.85.x from 0.85.0, 0.86.x from 0.86.2, 0.87.x from 0.87.1, 0.88.x from 0.88.0) and 0.88.1 hybrids with Expo modules: supported versions, detection, what is read from the Xcode project, sources, resources, Metro, limits. - [wifi-install.md](wifi-install.md): installing over Wi‑Fi without the cable, WSL2 pair records, Wi‑Fi troubleshooting. - [troubleshooting.md](troubleshooting.md): first-run checklist on the iPhone and fixes for common build, Metro and - signing problems, opening a dev-client app on Metro, the app icon, the Expo SDK 58 and 57 version messages, the + signing problems, opening a dev-client app on Metro, the app icon, the Expo SDK 58, 57 and 56 version messages, the warnings on versions newer than the verified ones, and what each `doctor --project` line means. - [libraries.md](libraries.md): library compatibility matrix (Expo and bare), tested on a physical iPhone. @@ -68,7 +68,10 @@ Historical specs and implementation plans, kept as written (some in Spanish; the React Native projects. - [design/specs/2026-10-27-expo-sdk-57-design.md](design/specs/2026-10-27-expo-sdk-57-design.md): Expo SDK 57 through a vendored Expo SwiftPM plugin. +- [design/specs/2026-11-11-expo-sdk-56-design.md](design/specs/2026-11-11-expo-sdk-56-design.md): Expo SDK 56 on SDK + 57's route. - [design/plans/2026-10-23-expo-xtool-cli.md](design/plans/2026-10-23-expo-xtool-cli.md): CLI implementation plan. - [design/plans/2026-10-26-bare-react-native.md](design/plans/2026-10-26-bare-react-native.md): bare React Native implementation plan. - [design/plans/2026-10-28-expo-sdk-57.md](design/plans/2026-10-28-expo-sdk-57.md): Expo SDK 57 implementation plan. +- [design/plans/2026-11-11-expo-sdk-56.md](design/plans/2026-11-11-expo-sdk-56.md): Expo SDK 56 implementation plan. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 63b20f7..f30141a 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -63,7 +63,8 @@ pushed to. React Native's scaffolder ships twice: as `patches/react-native+0.88.0.patch` and its byte-identical copy `react-native+0.88.1.patch`, applied to an installed 0.88.x, and as `vendor/rn-spm/`, pristine 0.88.0 with that patch -and `vendor/rn-spm/rn-xtool-edits.patch` (E1–E6) applied, for 0.85–0.87 and Expo SDK 57. A change to the scaffolder: +and `vendor/rn-spm/rn-xtool-edits.patch` (E1–E6) applied, for 0.85–0.87 and Expo SDK 56 and 57. A change to the +scaffolder: 1. Edits the vendored copy (`vendor/rn-spm/spm/*.js`), and documents the fix in [upstream/react-native-scaffolder.md](upstream/react-native-scaffolder.md) and the count in @@ -154,7 +155,7 @@ runner with no Swift and no Darwin SDK, uses only `GITHUB_TOKEN`, and never comp ### What it checks Daily (cron `23 5 * * *`, UTC), for each row of `SUPPORTED_LINES` in `src/versions.ts`, it creates a fresh project -with the newest published version of the line: `create-expo` 5.1.5 with `blank-typescript@sdk-57`, +with the newest published version of the line: `create-expo` 5.1.5 with `default@sdk-56`, `blank-typescript@sdk-57`, `blank-typescript@sdk-58` and `default@sdk-58`, and `@react-native-community/cli init` (the CLI pinned per line) with the newest 0.85.x, 0.86.x, 0.87.x and 0.88.x. On each project it runs three checks: @@ -187,9 +188,9 @@ The report job keeps one GitHub issue per broken line, labelled `drift` and titl ### Running it by hand - `gh workflow run drift-watch.yml -f mode=daily` (or "Run workflow" in the Actions tab) runs the daily check. -- `-f drill=` (`expo-57`, `expo-58`, `bare-0.85`, `bare-0.86`, `bare-0.87` or `bare-0.88`) marks that line - red for one daily run, with a `drill` step, to test the issue path end to end: the run opens or updates that line's - issue, and the next run without `drill` closes it. Any other value stops the report before it touches an issue. +- `-f drill=` (`expo-56`, `expo-57`, `expo-58`, `bare-0.85`, `bare-0.86`, `bare-0.87` or `bare-0.88`) marks + that line red for one daily run, with a `drill` step, to test the issue path end to end: the run opens or updates that + line's issue, and the next run without `drill` closes it. Any other value stops the report before it touches an issue. `drill` is ignored with `mode=explore`. - `-f mode=explore` runs the weekly exploration. - Locally, after `npm run build`: `node scripts/drift-watch.mjs` prints its subcommands. `check --existing` checks a @@ -198,7 +199,7 @@ The report job keeps one GitHub issue per broken line, labelled `drift` and titl ### Weekly exploration -Weekly (cron `47 5 * * 1`, Mondays, UTC), report only: the newest Expo SDK 54, 55 and 56 `blank-typescript` templates +Weekly (cron `47 5 * * 1`, Mondays, UTC), report only: the newest Expo SDK 54 and 55 `blank-typescript` templates and fresh bare React Native 0.81 to 0.84 projects (the newest patch of each, the CLI pinned per minor) go through the capability detector. The run summary gets an "Older lines (exploration, report only)" table: installed versions, scripts, artifacts, Expo plugin, Expo modules, podspec features, and the reason rn-xtool does not support the line. @@ -221,8 +222,9 @@ from `EXPLORE_RN_MINORS` and `EXPLORE_RN_CLI`, in `src/drift/targets.ts`. run (a network failure after the retry, a check that crashed or left no result) and when a `gh` call fails (a token or permission error, an issue list that cannot be read). That email is the only fallback when `gh` fails: nothing else reports it. Days with a network failure therefore send an email even when no line broke. -- **No compile, no device, no G4.** A green line can still fail G4 or the build, or crash on the device. The issue - body and the README say so; a compat-suite CI with a self-hosted runner would close the gap. +- **No compile, no device, no G4.** A green line can still fail G4 or the build (on Expo SDK 56 and 57 also the `jsi` + step's check of the ExpoModulesJSI interface), or crash on the device. The issue body and the README say so; a + compat-suite CI with a self-hosted runner would close the gap. - **Artifacts "unknown" stays green.** When `doctor --project` cannot check the React Native artifacts (network), the gates step stays green with `note: the React Native artifacts were not checked (network); they are checked again on the next run`. A line whose artifacts stay unchecked for days stays green meanwhile. diff --git a/docs/bare-react-native.md b/docs/bare-react-native.md index 36a5172..6bf4351 100644 --- a/docs/bare-react-native.md +++ b/docs/bare-react-native.md @@ -333,8 +333,11 @@ expo-modules-jsi nested after that (package-lock.json holds its place; neither a and `doctor` then stops on it; `npm update expo-modules-jsi` moves it to the top level without changing other packages. The SDK 58 checks of Expo apps apply to hybrids too ([how-it-works.md](how-it-works.md#expo-sdk-58), messages in -[troubleshooting.md](troubleshooting.md#expo-sdk-58)), and an `expo` older than SDK 58 stops the build. Verified on a -physical iPhone on 2026-10-28: a hybrid app on expo 58.0.21 and React Native 0.88.1 launched, with expo-haptics and an +[troubleshooting.md](troubleshooting.md#expo-sdk-58)), and an `expo` older than SDK 58 stops the build. Among them, +expo-file-system and expo-font are read where Expo's autolinking links them, as its CLI answers: one installed that +autolinking does not link and the app does not exclude stops the build (" is installed () but Expo's +autolinking does not link it for iOS, …"), and when the CLI cannot be asked, a `⚠` line says so. Verified on a physical +iPhone on 2026-10-28: a hybrid app on expo 58.0.21 and React Native 0.88.1 launched, with expo-haptics and an Objective-C module calling Swift working. `expo-constants` gets its `EXConstants.bundle/app.config` as in Expo apps. diff --git a/docs/design/plans/2026-11-11-expo-sdk-56.md b/docs/design/plans/2026-11-11-expo-sdk-56.md new file mode 100644 index 0000000..208fdf9 --- /dev/null +++ b/docs/design/plans/2026-11-11-expo-sdk-56.md @@ -0,0 +1,552 @@ +# Expo SDK 56 Implementation Plan + +**Goal:** `rn-xtool doctor | build | install | start | run` work on Expo SDK 56 projects (expo 56.x from 56.0.24, +react-native exactly 0.85.3), proved on a fresh `default@sdk-56` template built from zero, on the owner's device pass +and on the owner's SDK 56 app, with Expo SDK 57, Expo SDK 58 and bare 0.85 unchanged except for the generic fixes +listed. The row merges only after the owner's device pass. + +**Architecture:** SDK 56 runs on SDK 57's path: the vendored Expo 58.0.19 plugin, the vendored React Native 0.88.0 +scripts, the adapted 0.85.3 artifacts of the bare 0.85 line, the `jsi` step before `rn-spm`, and the precompiled modules +that ship in the npm packages (ExpoModulesCore, ExpoModulesWorklets, ExpoFileSystem, ExpoFont, ExpoImage and its +`spm-deps`). The line is one `SUPPORTED_LINES` row, which the gate, `doctor`, the overrides remedy and the drift watch +already read. Four generic changes close the spike's four gaps: a bundled jsi 56 patch, the JSI headers found in either +layout, a readable ExpoModulesJSI interface behind a guard, and vendored edit P7 (each Expo package at its podspec's +iOS floor). No code path branches on the SDK number. + +**Tech Stack:** TypeScript (Node 22.12+, ESM), vitest, `tsc --noEmit` as lint, the vendored Expo plugin (`vendor/expo-spm`, +CommonJS, MIT 650 Industries), the vendored RN scripts (`vendor/rn-spm`), patch-package, xtool 1.24.0, Swift 6.4 with the +Darwin SDK (investigation and proof only), `llvm-nm` (G4). + +**Spec:** `docs/design/specs/2026-11-11-expo-sdk-56-design.md` (approved 2026-11-11). The owner confirmed its +failure-walk rulings of rows 1–40; rows 41–46 await the owner's confirmation. This plan carries each row's owner below. + +## Global Constraints + +- Linux, Node 22.12+, Swift 6.4 (6.4.1 here), xtool 1.24.0, `IOS_MIN` 16.4, `SCAFFOLD_REVISION` 8, `ADAPTER_VERSION` + 1: unchanged. `JSI_HEADERS_GENERATOR_VERSION` goes from 1 to 2 only on Task 4's exit B2. +- **The row, verbatim**, first in `SUPPORTED_LINES` (before `expo-57`): + `{ kind: "expo", sdk: 56, plugin: "vendored", policy: "floor", scripts: "vendored", artifacts: "adapted", pins: { expo: "56.0.24", "react-native": "0.85.3", "expo-modules-core": "56.0.27", "expo-modules-jsi": "56.0.14", "expo-modules-autolinking": "56.0.24", "expo-file-system": "56.0.11", "expo-font": "56.0.7" }, templates: ["default"], createExpo: "5.1.5" }`. +- **Bundled patches after Task 2 (seven):** `expo+58.0.21.patch`, `expo-modules-autolinking+58.0.16.patch`, + `expo-modules-jsi+56.0.14.patch`, `expo-modules-jsi+57.1.3.patch`, `expo-modules-jsi+58.0.21.patch`, + `react-native+0.88.0.patch`, `react-native+0.88.1.patch`. `patches/expo+58.0.21.patch` is not edited. +- `vendor/expo-spm` stays expo 58.0.19 (`EXPO_TARBALL`, `EXPO_INTEGRITY` unchanged); its vendored-only edits become + P1–P7. `vendor/rn-spm` is not touched. +- **No version branch.** `grep -rnE '\b56\.' src` lists only the row. No hard-coded iOS floor in `vendor/expo-spm`. +- **Texts are verbatim** (`${…}` marks a value): + - Refusal: `Expo SDK ${n} is not supported; rn-xtool supports SDK 56 (expo 56.0.24 or newer 56.x), SDK 57 (expo 57.0.31 or newer 57.x) and SDK 58 or newer.` + - G1 prefix: `Expo SDK 56 needs react-native 0.85.3 and at least expo 56.0.24, expo-modules-core 56.0.27, expo-modules-jsi 56.0.14, expo-modules-autolinking 56.0.24, expo-file-system 56.0.11 and expo-font 56.0.7; installed: ${list}. ${remedy}` (the remedy as `floorRemedy` builds it for SDK 57 and 58). + - Warning: `⚠ Newer than the Expo SDK 56 set this rn-xtool release was verified with: ${list}. Verified: expo 56.0.24, react-native 0.85.3, expo-modules-core 56.0.27, expo-modules-jsi 56.0.14, expo-modules-autolinking 56.0.24, expo-file-system 56.0.11 and expo-font 56.0.7. The build continues; if it fails or the app crashes at launch, report it at https://github.com/WillyAntunez/react-native-xtool/issues.` + - `doctor --project` versions line: `Expo SDK 56: expo 56.0.24 (verified 56.0.24), react-native 0.85.3 (verified 0.85.3)`. + - Overrides block (patch failure on SDK 56): `"overrides": { "expo-modules-core": "56.0.27", "expo-modules-jsi": "56.0.14", "expo-modules-autolinking": "56.0.24" }`. + - Headers error (Task 3): `ExpoModulesJSI needs React Native's headers at ${dir}, which does not exist. rnArtifactsDir must hold the adapted slots of the project's React Native version, as rn-xtool's rn-artifacts step writes them.` + - Missing `NativeState.h` (Task 3): `expo-modules-jsi ${jsiVersion} ships no NativeState.h (looked in ${include}/Public and ${include}); cannot make ExpoModulesJSIHeaders.xcframework.` + - Local include (Task 3): `${header} of expo-modules-jsi ${jsiVersion} includes "${name}", which is not next to it in ${folder}; cannot make ExpoModulesJSIHeaders.xcframework.` (`${header}` is the including header's path in `${dir}`, `${folder}` its folder: for NativeState.h, `NativeState.h` and `${dir}`); for an include that points outside `${dir}` (`../x.h`, an absolute path), `which points outside ${dir}` instead. + - Guard (Task 4): ``The ExpoModulesJSI.swiftinterface built for expo-modules-jsi ${jsiVersion} (${compiler}) has ${n} ${n === 1 ? "line" : "lines"} no Swift compiler can parse, for example line ${line}: ${text}. Every module that imports ExpoModulesJSI would fail to compile.${lever} See https://github.com/WillyAntunez/react-native-xtool/blob/main/docs/troubleshooting.md#unreadable-expomodulesjsi-interface, and report it at https://github.com/WillyAntunez/react-native-xtool/issues with the output of `rn-xtool doctor --report`.`` (`compiler` is the value of the interface's `// swift-compiler-version:` line, else `unknown compiler`; `line` and `text` are the first unreadable line's; `lever` is `` It was written by Swift ${found}, and this rn-xtool release was verified with Swift ${SWIFT_VERSION}: a newer or older Swift is the likely cause.`` when the `Swift version` in `compiler` differs from `SWIFT_VERSION` in major.minor, else empty.) + - Drill error: `unknown drift line "x"; lines: expo-56, expo-57, expo-58, bare-0.85, bare-0.86, bare-0.87, bare-0.88`. +- **Privacy.** No absolute home path, Team ID, UDID, Apple ID, e-mail or real IP in committed files, tests or the PR + body. Placeholders: `/home/me`, `TEAMID0000`, `192.168.1.2`. Scratch folders are written `/…`; the + owner's work app is "the owner's SDK 56 app", with no name, path or library list. +- **Heavy steps** (builds, downloads) appear only in Task 4 Step 1 and Task 6, each "needs the owner's go-ahead". The + machine has under 9 GB free (7.2 GB on 2026-11-11). Before each build `df -h ~` must show at least 5 GB free, + otherwise stop and ask. Each heavy step deletes only the outputs it created, by literal path, after its results are + recorded; before any `rm -rf` of more than one path, `ls -ld` each path and check that none is a symlink + (`find -maxdepth 0 -type l` prints nothing). +- Every task that changes code ends with `npm test && npm run lint` green. Every commit runs `npm run scan:private` after + `git add`, before `git commit`. +- Commits: Conventional Commits in English, the subject given in the task (≤ 50 characters), no body, one logical + change each, red before green, no scratch code. Never push, rebase, amend or stash; the controller pushes with + `git push -u origin feature/expo-sdk-56` when the owner asks, and checks that `@{u}` is `origin/feature/expo-sdk-56`. + +## Failure-walk owners + +The spec's rows with their rulings and owners, confirmed by the owner on 2026-11-11 for rows 1–40; rows 41–46 carry a +ruling awaiting the owner's confirmation. + +| # | Hop | Ruling | Owner | +|---|---|---|---| +| 1 | npm install: ERESOLVE or network | accept | Task 6 Step 1 records the install; Task 7 adds a troubleshooting entry only if one appears | +| 2 | npm install: macro binary left out | handle | Task 1 expo.test `checks the expo-modules-macros copy the vendored plugin finds on SDK 56` | +| 3 | lockfile holds core, file-system or font below the set | handle | Task 1 expo.test `names each SDK 56 pin below the floor`, `reads expo-file-system and expo-font where autolinking links them on SDK 56` | +| 4 | expo-image on another core | handle | G4 unchanged; Task 6 Step 2 | +| 5 | nested expo-modules-jsi | handle | Task 1 expo.test `refuses a nested expo-modules-jsi on SDK 56` | +| 6 | react-native other than 0.85.3 | handle | Task 1 expo.test `refuses react-native other than 0.85.3` | +| 7 | newer 56.x | accept | Task 1 plan note; expo.test `warns and continues on a newer 56.x`; the daily watch | +| 8 | another SDK's package | handle | Task 1 expo.test `refuses a package of another SDK's line on SDK 56` | +| 9 | SDK 55 or older | handle | Task 1 expo.test `rejects SDK %i`; versions.test `lists the supported Expo SDKs from the table` | +| 10 | hybrid on SDK 56 | handle | existing bare.test `refuses a hybrid app on Expo SDK %s` (56 case), unchanged | +| 11 | jsi patch fails on a newer 56.x | handle | Task 2 patches.test `names the SDK 56 overrides when its jsi patch fails on a newer 56.x`; Task 1 targets.test | +| 12 | another SDK's patch staged | handle | Task 2 patches.test `never stages another SDK's patch on SDK 56` | +| 13 | a later core imports `CppError.message` | accept | Task 7 troubleshooting entry; G4 unchanged | +| 14 | `rn-artifacts` network | accept | as ruled for bare 0.85; Task 7 sizes | +| 15 | jsi compile fails | handle (this set), accept (later toolchain) | Task 6 Step 1; owner's ruling 1 | +| 16 | `rnArtifactsDir` wrong | handle | Task 3 jsi.test `stops when the React Native headers are missing` | +| 17 | `NativeState.h` or a local include missing, or an include pointing outside the folder | handle | Task 3 jsiHeaders.test `names a local include that is not next to NativeState.h`, `names the header that holds an include that is not there`, `names a nested header's include that is not next to it`, `refuses an include that points outside the folder: %s`, `resolves an include next to the header that holds it, in a nested folder`, `follows #import as #include`, `a failed synthesis leaves no stamped xcframework` | +| 18 | stale or partial headers tree | handle | existing jsiHeaders tests (`rewrites when the interface changes`); Task 4 jsiHeaders.test `refuses an unreadable interface even when the stamp says the tree is current` (B1 taken) | +| 19 | unreadable lines in an unknown shape: an empty slot anywhere in an `extension` line's inheritance list | handle | Task 4 jsiInterface.test `stops on a broken line it does not know`, the groups `unreadableInterfaceLines on other shapes` (`flags %s`, `flags a line that ends its list before %s`, `does not flag %s`) and `names a Swift other than the verified one as the likely cause` | +| 20 | cleanup removes too much | handle | not reached: Task 4 took B1, which strips no text from the interface; the compiler stops printing the stubs | +| 21 | the fix changes SDK 57 or 58 | handle | Task 6 Step 3 (Task 4's re-proof) | +| 22 | podspec asks for more iOS | handle | Task 5 vendor-expo-spm.test `P7 reads the iOS deployment target a podspec declares`, `P7 raises a module to its podspec's iOS floor` | +| 23 | podspec above the App's 16.4 | handle (awaiting the owner's confirmation) | P7 caps a podspec's floor at the App's target and warns once per build: vendor-expo-spm.test `P7 caps a podspec's floor at the app's deployment target and warns once`, `P7 leaves a module's own spm.config.json floor as it was`, `P7 takes a podspec's floor uncapped and silent without the app's deployment target`, `P7 writes its warnings to the notes file rn-xtool prints, else to stderr` and `P7 takes core's podspec floor into a sibling's generated manifest`; rnSpm.test `prints the Expo plugin's warnings once after rn-spm, however many times it ran`; rn-spm-generate.test `clears inherited Expo plugin variables when --expo-plugin is absent`; Task 7 troubleshooting entry | +| 24 | podspec platform P7 cannot read, or misreads (inside an `if`; several assignments, the highest taken; an unterminated heredoc) | accept (awaiting the owner's confirmation) | Task 5 README limits; P7 test asserts `null`; `P7 reads only what Ruby runs, and versions SwiftPM takes` | +| 25 | P7 changes SDK 57 | handle | Task 5 test (never lowered); Task 6 Step 3 `platforms:` check | +| 26 | JSI and core C++ layout skew | accept | Task 7 docs (G4's limit); owner's ruling 2 | +| 27 | ExpoModulesWorkletsAdapter left out | handle | proven only by the owner's device pass (Task 6 Step 4), pending; Task 7 note | +| 28 | stale scaffold patches, Xcode-only resources | accept | existing behaviour | +| 29 | AppleDouble and xattrs | handle | existing vendor-expo-spm.test `P5 extracts without AppleDouble entries or xattr warnings` | +| 30 | damaged tarball | accept | Task 7 troubleshooting line | +| 31 | ExpoImage `spm-deps` | handle | proven only by the owner's device pass (Task 6 Step 4), pending; Steps 1 and 2 checked `Frameworks/` and G4 at build time | +| 32 | G4 false positive | handle | Task 6 Steps 1–2 | +| 33 | Icon Composer icon | accept | Task 7 notes | +| 34 | unseen compile failure | handle | Task 6 Step 1 | +| 35 | runtime on the device | handle | proven only by the owner's device pass (Task 6 Step 4), pending | +| 36 | the owner's SDK 56 app | handle | proven only by the owner's own pass with that app (Task 6 Step 5), pending | +| 37 | newer 56.x over time | handle (gates, patches), accept (compile, interface, G4) | Task 1 targets.test; RELEASING limits | +| 38 | newer Swift 6.4.x | accept | owner's ruling 1 | +| 39 | SDK 56 leaves the exploration | accept | Task 7 explore.test | +| 40 | disk | accept | Task 7 sizes | +| 41 | two copies of file-system or font, hoisted and nested under expo, or anywhere else autolinking links one; one installed that autolinking does not link: skipped only when the app excludes it, refused otherwise | handle (awaiting the owner's confirmation) | Task 1 expo.test `reads expo-file-system and expo-font where autolinking links them on SDK 56`, `gates the %s copy the app lists on SDK 56`, `names expo-font not installed when autolinking links no copy on SDK 56`, `skips the %s pin expo.autolinking.exclude leaves unlinked on SDK 56` and `… on SDK 58`, `skips the %s pin expo.autolinking.%s.exclude leaves unlinked on SDK 56`, `gates a pin a platform list takes back out of the exclusions on SDK 56`, `refuses an installed expo-font autolinking does not link (%s) on SDK 56`, `refuses an installed expo-file-system autolinking does not link on SDK 58`, group `reads the expo-font copy autolinking's own CLI links` (D, A, B, C), group `through the app's autolinking CLI` on SDK 58, `gates the library's copy the app's autolinking links on SDK 58` | +| 42 | pnpm, Yarn PnP or no flat `node_modules` | accept (awaiting the owner's confirmation) | existing early refusal; README "Before you start" (npm or Yarn classic), troubleshooting "pnpm and Yarn PnP" | +| 43 | SDK 56 macros expanded by rn-xtool's expo-modules-macros 0.22.0 | accept (awaiting the owner's confirmation) | Task 6 Step 1 for this set; Task 7 note in `vendor/expo-spm/README.md` | +| 44 | the autolinking CLI cannot run at gate time (its CLI not found, a non-zero exit, stopped by a signal, no answer within 20 s, a failure to start, an unreadable answer); the user learns it by the gate's `⚠ rn-xtool could not ask Expo's autolinking …` line, which names that reason | handle (awaiting the owner's confirmation) | Task 1 expo.test `falls back to the two-copy rule when the CLI %s`, group `through the fallback rule` on SDK 58; final-review fix expo.test `says once that autolinking could not be asked when the CLI %s`, `says once that autolinking could not be asked when the CLI does not answer in time`, `says nothing about autolinking when the CLI answers`, and the group `the gate's line when autolinking cannot be asked` (SDK 56, a hybrid app on SDK 58, none on SDK 57, `asks within 20 s`); bare.test `a hybrid on a newer 0.88.x stops at G1`, `gates a hybrid app on the SDK 58 set`; doctor.test `shows that the version check could not ask autolinking`; troubleshooting "Expo SDK 58" | +| 45 | jsi build: a build interrupted during `jsi` leaves a truncated module cache | handle (awaiting the owner's confirmation) | Task 6 fix: jsi.test `--clean removes the jsi build's scratch before the script runs, and nothing else in jsi-out`, `keeps the jsi build's scratch without --clean`, `names the module cache and the remedy when the build fails on a module file cut short`, `leaves any other jsi failure as it is`, `is the script's scratch folder`; build.test `--clean asks the jsi step for a clean build on every kind that has one`; troubleshooting "Interrupted build" | +| 46 | xtool-build: a build interrupted during `xtool-build` leaves a truncated module cache in `ios-xtool/.build`; `build`, `install` and `install --network` then fail on it | handle (awaiting the owner's confirmation) | final-review fix: moduleCache.test `under ios-xtool/.build names the interrupted xtool-build and deleting that folder`, `under the jsi build's scratch names the interrupted jsi step, deleting that folder and --clean`, `anywhere else gives no paragraph`, `gives no paragraph when one of the files it names is elsewhere, nor without clang's error`, `finds the folder when the project is reached through a symlink and clang names the real path`, `appends the paragraph to a failure's message, keeping the failure as its cause`, `leaves a failure without that error, or with the file elsewhere, as it is`; xtool.test `devBuild shows and keeps xtool's output by default, and explains a module cache a killed build left`, `devBuild passes any other failure through unchanged`; install fix: xtool.test `devRun explains a module cache a killed build left, through install's explanations, keeping the failure`, `devRun leaves any other failure to install's explanations as before`, devBuildIpa `explains a module cache a killed build left, keeping the failure, and passes any other through`, moduleCache.test `finds the folder when the project's path has an apostrophe in it`; jsi.test `leaves a module file error outside the jsi build's scratch as it is`; troubleshooting "Interrupted build" | + +## Review Focus + +1. **Where npm puts expo-file-system and expo-font.** SDK 56 hoists them; a lockfile can nest one under `expo` next to + a top-level copy of another version. The gate must read the copy autolinking links, as autolinking's own CLI + answers (Task 1 tests `reads expo-file-system and expo-font where autolinking links them on SDK 56`, `gates the %s + copy the app lists on SDK 56` and the group `reads the expo-font copy autolinking's own CLI links`; rows 41 and 44). +2. **A jsi newer than 56.0.14.** It must get 56.0.14's patch, never 57.1.3's, and a patch failure must name the SDK 56 + overrides (Task 2 tests `never stages another SDK's patch on SDK 56` and `names the SDK 56 overrides when its jsi + patch fails on a newer 56.x`). +3. **A jsi package in either header layout**, including one whose `NativeState.h` includes a header that is not there + (Task 3 tests `writes jsi 56's layout: NativeState.h from include/ with its local includes` and `names a local + include that is not next to NativeState.h`). +4. **An interface with an unreadable line the fix does not know**, from a newer jsi or Swift 6.4.x: it must stop at + `jsi` by name, never reach `xtool-build` (Task 4 test `stops on a broken line it does not know`). +5. **Podspec platform forms** beyond the template's: one line or several, `s.ios.deployment_target`, + `s.platform = :ios, '…'`, a `test_spec`'s own platforms, a variable (Task 5 test `P7 reads the iOS deployment + target a podspec declares`). +6. Before the final verdict, the reviewer answers without hints: "Name three ways this fails in production that no + test covers." Any answer not in the failure-walk table goes to the owner as a decision, not to the implementer as a + fix. + +--- + +### Task 1: The SDK 56 row and its gate + +Plan note (row 7, accept): a newer 56.x of a pinned package builds with the newer-than warning, as on SDK 57 and 58; +the daily watch creates the newest 56.x set every day. + +**Files:** +- Modify: + - `src/versions.ts`: the row first in `SUPPORTED_LINES` (`:71`); the table comment (`:66-70`: SDK 56 and 57 build + through the vendored plugin); `supportedExpoList()` (new, next to `supportedRnList`, `:240`). + - `src/project/expo.ts:377-383`: the refusal uses `supportedExpoList()`. + - Comments only: `src/project/types.ts:23`, `src/paths.ts:10`, `src/pipeline/rnSpm.ts:74` ("SDK 56 and 57"). + - `tests/support/expo57.ts`: export `fakeExpoModules`, which `fakeExpo57Modules` now calls. +- Create: + - `tests/support/expo56.ts`. + - `tests/fixtures/expo-56/`: `app.json` (name and slug `Expo56`, `ios.bundleIdentifier` `com.anonymous.expo56`, + `ios.icon` `./assets/expo.icon` as the template has it), `package.json` (`"expo": "~56.0.24"`, + `"react-native": "0.85.3"`), `ios/Expo56/AppDelegate.swift` (a copy of + `tests/fixtures/expo-57/ios/Spike57/AppDelegate.swift`: the gate tests need only the target folder). +- Test: `tests/versions.test.ts`, `tests/project/expo.test.ts`, `tests/capabilities.test.ts`, `tests/doctor.test.ts`, + `tests/drift/targets.test.ts`, `tests/drift/issues.test.ts` + +**Interfaces:** +- Produces: + ```ts + // src/versions.ts + /** "SDK 56 (expo 56.0.24 or newer 56.x), SDK 57 (expo 57.0.31 or newer 57.x) and SDK 58 or newer" */ + export function supportedExpoList(): string; + // every Expo row but the last: `SDK ${sdk} (expo ${pins.expo} or newer ${sdk}.x)`; the last: `SDK ${sdk} or newer`; andList + // tests/support/expo57.ts + export async function fakeExpoModules( + dir: string, + pins: Partial>, + overrides?: Partial>, + nested?: Partial>, + ): Promise; + // tests/support/expo56.ts + export const EXPO56_PINS: Partial>; // the row's pins, written out + export async function fakeExpo56Modules(dir: string, overrides?: …, nested?: …): Promise; // fakeExpoModules(dir, EXPO56_PINS, …) + ``` +- Consumes: `checkExpoPackages`, `expoMacrosBinaryError`, `vendoredExpoPlugin` (unchanged). + +- [ ] **Step 1: Write the failing tests.** + - versions.test: + - `holds every supported line in one table`: ids `["expo-56", "expo-57", "expo-58", "bare-0.85", "bare-0.86", "bare-0.87", "bare-0.88"]`; the first row equals the Global Constraints row with `pins: EXPO56_PINS`. + - `lists the supported Expo SDKs from the table` (new): `supportedExpoList()` is `SDK 56 (expo 56.0.24 or newer 56.x), SDK 57 (expo 57.0.31 or newer 57.x) and SDK 58 or newer`. + - expo.test: + - `rejects SDK %i` (`:81`): `it.each([55, 54])`, the refusal text above. + - `has the SDK 57 pins and plugin in the supported table` (`:237-242`): `[expoPluginFor(55), expoPluginFor(56), expoPluginFor(57), expoPluginFor(58), expoPluginFor(59)]` is `[undefined, "vendored", "vendored", "installed", "installed"]`. + - a new `describe("Expo SDK 56")` on the `expo-56` fixture with `fakeExpo56Modules`: + - `has the SDK 56 pins in the supported table`: `expoPinsFor(56)` equals `EXPO56_PINS`; `expoPinPolicyFor(56)` is `"floor"`. + - `accepts the SDK 56 floor set`: resolves to `{ sdkVersion: 56, rnVersion: "0.85.3", rnScripts: "vendored", expoPlugin: "vendored" }`, `iosTargetDir` is `/ios/Expo56`, `readExpoPins(dir, 56)` equals `EXPO56_PINS`, `log` not called. + - `names each SDK 56 pin below the floor`: `it.each` over expo 56.0.23, expo-modules-core 56.0.26, expo-modules-jsi 56.0.13, expo-modules-autolinking 56.0.23, expo-file-system 56.0.10, expo-font 56.0.6; the message starts with the G1 prefix followed by `${name} ${version}. `; it is a `VersionGateError`. + - `refuses react-native other than 0.85.3`: 0.85.2 → `${prefix}react-native 0.85.2. Run \`npx expo install react-native@0.85.3\`.`; 0.85.4 → the same plus ` React Native 0.85.4 is newer than this rn-xtool release supports: pin react-native to 0.85.3, or update rn-xtool.` + - `warns and continues on a newer 56.x`: expo 56.0.25 and expo-modules-jsi 56.0.15 → resolves; `log` called once with the warning text above, `${list}` = `expo 56.0.25, expo-modules-jsi 56.0.15`. + - `refuses a package of another SDK's line on SDK 56`: expo-modules-jsi 57.1.3 → G1 naming `expo-modules-jsi 57.1.3`; `log` not called. + - `reads expo-file-system and expo-font where autolinking links them on SDK 56`: the default (hoisted) set is accepted; with a nested `node_modules/expo/node_modules/expo-font` 56.0.6 next to a top-level 56.0.7 that nothing the app lists reaches, G1 names `expo-font 56.0.6`. + - `gates the %s copy the app lists on SDK 56` (row 41): when the app lists the package, its top-level copy is the one autolinking links; below the floor it is refused next to a nested copy at the floor, and at the floor it passes next to a nested copy below it. + - `refuses a nested expo-modules-jsi on SDK 56`: core's own jsi 56.0.14 nested under `node_modules/expo-modules-core`, a hoisted stray 57.1.3 → the error starts with `expo-modules-jsi 56.0.14 resolves from node_modules/expo-modules-core/node_modules/expo-modules-jsi, not from the project's top-level node_modules`. + - `checks the expo-modules-macros copy the vendored plugin finds on SDK 56`: through the SDK 56 row (`checkExpoPackages(root, 56)`, `process.arch` set to `riscv64` for the call), G3 throws `expo-modules-macros 0.22.0 has no Linux binary for riscv64 (@expo/modules-macros-linux-riscv64); reinstall react-native-xtool without --omit=optional.` + - capabilities.test: + - `gives unsupported versions a reason` (`:1006-1008`): the Expo case becomes `expoOther("55.0.4", "0.83.2")` → `Expo SDK 55: expo ships no SwiftPM plugin; React Native 0.83: no SwiftPM scripts; support comes with the translator`. + - `says when an Expo SDK below 57 ships the plugin` (`:1030`): renamed `… below 56 …`, on `expoOther("55.0.4", "0.83.2")` → `Expo SDK 55: expo ships its SwiftPM plugin; React Native 0.83: no SwiftPM scripts; support comes with the translator`. + - `has no reason for the lines it supports`: adds `expoOther("56.0.24", "0.85.3")` → `undefined`. + - doctor.test, the capability-line table (`:1036-1040`): adds `["versions", "Expo 56", expo(56, "56.0.24", "0.85.3"), "ok", "Expo SDK 56: expo 56.0.24 (verified 56.0.24), react-native 0.85.3 (verified 0.85.3)"]`; the `"Expo 56"` fail row becomes `["versions", "Expo 55", { ...expo(55, "55.0.0", "0.83.2"), expoPlugin: "none" }, "fail", "Expo SDK 55: expo ships no SwiftPM plugin; React Native 0.83: no SwiftPM scripts; support comes with the translator"]`. + - drift targets.test `one target per template and bare line` (`:30`): `expo-56/default` first, equal to `{ id: "expo-56/default", slug: "expo-56-default", line: "expo-56", title: "Drift: Expo SDK 56", kind: "expo", sdk: 56, template: "default", createExpo: "5.1.5" }`. + - drift issues.test (`:142`, `:153`): the drill error text above; `checkDrill("expo-56")` does not throw. +- [ ] **Step 2: Run** `npx vitest run tests/versions.test.ts tests/project tests/capabilities.test.ts tests/doctor.test.ts tests/drift` → FAIL (no SDK 56 row). +- [ ] **Step 3: Implement** the row, `supportedExpoList()`, the refusal, the comments, the fixture and the test support. +- [ ] **Step 4: Run** the same tests, then `npm test && npm run lint` → PASS. `grep -rnE '\b56\.' src` lists only the row. +- [ ] **Step 5: Commit** `git add src tests && npm run scan:private && git commit -m "feat: add the Expo SDK 56 line"` + +### Task 2: The jsi 56 patch + +**Files:** +- Create: `patches/expo-modules-jsi+56.0.14.patch`: patch-package format, one hunk `@@ -82,7 +82,7 @@` in + `node_modules/expo-modules-jsi/apple/Sources/ExpoModulesJSI/Runtime/Values/JavaScriptError.swift`, + ` public var message: String {` → ` var message: String {` (the same change as `expo-modules-jsi+57.1.3.patch`). +- Test: `tests/patches.test.ts` + +**Interfaces:** none new. `selectBundledPatches` and `floorRemedy` are unchanged; the tests pin their SDK 56 answers. + +- [ ] **Step 1: Write the failing tests** in `tests/patches.test.ts`: + - `has exactly 7 patch-package files` (was 6, `:88`): the seven names of Global Constraints. + - `stages only the jsi patch on an SDK 56 project`: expo 56.0.24, expo-modules-autolinking 56.0.24, expo-modules-jsi 56.0.14, react-native 0.85.3 → `selectBundledPatches(root, bundled, { lineOnly: true })` is `["expo-modules-jsi+56.0.14.patch"]`. + - `never stages another SDK's patch on SDK 56`: expo 56.0.25, autolinking 56.0.25, jsi 56.0.15, react-native 0.85.3 → `["expo-modules-jsi+56.0.14.patch"]`. + - `names the SDK 56 overrides when its jsi patch fails on a newer 56.x`: expo 56.0.24, jsi 56.0.15, an exec that fails naming `node_modules/expo-modules-jsi` → the error matches `/^rn-xtool could not patch expo-modules-jsi@56\.0\.15 \(patch file: expo-modules-jsi\+56\.0\.14\.patch\)/`, contains the SDK 56 overrides block of Global Constraints, and does not contain `pin "expo-modules-jsi"`. + - In `describe("a bundled patch over a package an earlier release patched differently")` (`:506`): `jsiProject` takes `{ version, before }` (installed jsi version, number of filler lines before the doc comment; today's call is `{ version: "58.0.21", before: 87 }`). New test `applies the SDK 56 jsi patch to the original file`: `{ version: "56.0.14", before: 81 }`, `applyPatches(root, undefined, { rnScripts: "vendored", expoPlugin: "vendored" })` with the real patch-package → the file contains `\n var message: String {\n` (timeout 30 s). + - `stages only the jsi patch on an SDK 57 project` and `never stages another SDK's patch on SDK 57` stay as they are: 57 still gets only `expo-modules-jsi+57.1.3.patch`. +- [ ] **Step 2: Run** `npx vitest run tests/patches.test.ts` → FAIL (the patch file is missing). +- [ ] **Step 3: Implement**: the spike app's `node_modules/expo-modules-jsi` is already patched, so copy its `JavaScriptError.swift` to a scratch folder, restore line 85 to ` public var message: String {` (the pristine file; patch-package changed nothing else), then write the patch with `git diff --no-index` and rewrite its header to patch-package's form as `docs/RELEASING.md` describes. Task 6 Step 1 applies it to a fresh install. +- [ ] **Step 4: Run** the same file, then `npm test && npm run lint` → PASS (`every bundled patch parses as patch-package reads it` covers the new file). +- [ ] **Step 5: Commit** `git add patches tests && npm run scan:private && git commit -m "feat: patch expo-modules-jsi 56 for Swift 6.4"` + +### Task 3: JSI headers in either layout, and the version-free texts + +**Files:** +- Modify: `src/pipeline/jsiHeaders.ts` (`:88-101`, `:126`), `src/pipeline/jsi.ts:43-44`, `src/commands/build.ts:537`, + `tests/support/fakeJsiBuild.ts` +- Test: `tests/jsiHeaders.test.ts`, `tests/jsi.test.ts` + +**Interfaces:** +- Produces: + ```ts + // src/pipeline/jsiHeaders.ts + /** + * The public C++ headers of expo-modules-jsi `jsiVersion` at `jsiDir`: `dir` is + * `/apple/Sources/ExpoModulesJSI-Cxx/include/Public` when it holds NativeState.h (jsi 57 and newer), else + * `…/include` (jsi 56); `files` is "NativeState.h", then each header it includes with quotes, transitively, found in + * `dir`, in include order, each once. Throws the missing-NativeState.h or the local-include text (Global Constraints). + */ + export function nativeStateHeaders(jsiDir: string, jsiVersion: string): { dir: string; files: string[] }; + // writeJsiHeadersXcframework: unchanged signature; copies `files` (relative paths kept) into each slice's + // Headers/ExpoModulesJSI. JSI_HEADERS_MODULE_MAP is unchanged. + // tests/support/fakeJsiBuild.ts + export const FAKE_NATIVE_STATE_FLAT: string; // '// NativeState.h\n#pragma once\n#include \n#include "RetainedSwiftPointer.h"\n' + export const FAKE_RETAINED_POINTER: string; // '// RetainedSwiftPointer.h\n#pragma once\n#include \n' + export function makeFakeJsiBuild(dir: string, opts?: { layout?: "public" | "flat" }): { objectsDir: string; jsiDir: string }; + // "public" (default): today's files; "flat": NativeState.h and RetainedSwiftPointer.h directly under include/ + ``` +- `src/commands/build.ts:537` reads `internal error: the vendored-plugin jsi step has no React Native artifacts (rn-artifacts was not planned and rnArtifactsDir is unset)`. + +- [ ] **Step 1: Write the failing tests** in `tests/jsiHeaders.test.ts`: + - `writes jsi 56's layout: NativeState.h from include/ with its local includes`: `setup("56.0.14")` on `makeFakeJsiBuild(dir, { layout: "flat" })` → `"written"`; the file list is the one of `writes 58's tarball layout` plus `ios-arm64/Headers/ExpoModulesJSI/RetainedSwiftPointer.h` and `ios-arm64_x86_64-simulator/Headers/ExpoModulesJSI/RetainedSwiftPointer.h`; in each slice `NativeState.h` equals `FAKE_NATIVE_STATE_FLAT`, `RetainedSwiftPointer.h` equals `FAKE_RETAINED_POINTER`, `module.modulemap` equals `JSI_HEADERS_MODULE_MAP`. + - `writes 58's tarball layout` stays as it is (57's layout gets no extra file). + - `prefers include/Public when both layouts hold NativeState.h`: both written, different contents → the copied file equals the `Public/` one. + - `names a local include that is not next to NativeState.h`: the flat layout without `RetainedSwiftPointer.h` → rejects with the local-include text (`${name}` `RetainedSwiftPointer.h`, `${dir}` the `include` dir, version 56.0.14); neither the xcframework, a `*.tmp-*` dir nor the stamp exists. + - `a failed synthesis leaves no stamped xcframework` (`:167`): the expected text becomes the missing-NativeState.h text with `${include}` = `/apple/Sources/ExpoModulesJSI-Cxx/include`. +- [ ] **Step 2: Run** `npx vitest run tests/jsiHeaders.test.ts` → FAIL. +- [ ] **Step 3: Implement** `nativeStateHeaders` and its use in `writeJsiHeadersXcframework` (the input check runs it before anything is written). +- [ ] **Step 4: Run** `npx vitest run tests/jsiHeaders.test.ts`, then `npm test && npm run lint` → PASS. +- [ ] **Step 5: Commit** `git add src/pipeline/jsiHeaders.ts tests/jsiHeaders.test.ts tests/support/fakeJsiBuild.ts && npm run scan:private && git commit -m "feat: find NativeState.h in either jsi layout"` +- [ ] **Step 6: Write the failing tests** in `tests/jsi.test.ts`: `stops when the React Native headers are missing` and `stops when only the dependencies headers are missing` (`:41-61`) expect the headers error of Global Constraints. **Run** `npx vitest run tests/jsi.test.ts` → FAIL. +- [ ] **Step 7: Implement** the two texts (`jsi.ts`, `build.ts:537`). **Run** `npx vitest run tests/jsi.test.ts tests/build.test.ts`, then `npm test && npm run lint` → PASS. +- [ ] **Step 8: Commit** `git add src/pipeline/jsi.ts src/commands/build.ts tests/jsi.test.ts && npm run scan:private && git commit -m "fix: drop 0.86.3 from the jsi step's errors"` + +### Task 4: A readable ExpoModulesJSI interface (investigation, then one of two exits) + +The guard ships on both exits; the owner picks the exit at Step 2 on the evidence of Step 1. Plan note (row 21): the +re-proof of SDK 57 and 58 that this task owns runs in Task 6 Step 3, once, after Task 5 (spec Decision 10). + +**Step 2 ruling: B1, source-hunk variant.** Step 1 found the cause in jsi 56's source, not in the toolchain: a fresh +SDK 57 interface (jsi 57.1.3) on Swift 6.4.1 has no unreadable line, with the same module flags, because 57.1.3 marks +the four conformances of generic types to the internal `~Copyable` `JSIRepresentable` `@_spi(Internal)`. The same +four marks in the jsi 56 patch (Step 10) give an interface with no unreadable line that differs from the baseline only +by the removed stubs, and an unchanged `llvm-nm` symbol list (spec, Approaches, "Outcome"). The B1 test is patches.test +`the SDK 56 jsi patch carries the interface fix`; B2's Step 8 tests and fixture were not written. + +**Files:** +- Create: `src/pipeline/jsiInterface.ts`, `tests/jsiInterface.test.ts`, + `tests/fixtures/jsi-interface/ExpoModulesJSI-56.0.14.swiftinterface` (from `$S/jsi56.swiftinterface` of Step 1: its + four header lines, then its stub block, from the `@available(*, unavailable)` line before the first + `Swift::Optional` stub through `internal protocol _ConstraintThatIsNotPartOfTheAPIOfThisLibrary {}`, verbatim; + checked to hold no absolute path before it is added). +- Exit B2 also creates `tests/fixtures/jsi-interface/ExpoModulesJSI-56.0.14.cleaned.swiftinterface` (the expected + output, written by hand from the fixture: the four pairs removed, nothing else). +- Modify: `src/pipeline/jsiHeaders.ts` (the interface is written through `readableJsiInterface` instead of copied; + B2: `JSI_HEADERS_GENERATOR_VERSION = 2`); B1 instead: `scripts/build-expo-modules-jsi.sh` (the flag) or + `patches/expo-modules-jsi+56.0.14.patch` (a source hunk). +- Test: `tests/jsiInterface.test.ts`, `tests/jsiHeaders.test.ts`, and on B1 `tests/jsi.test.ts` + +**Interfaces:** +- Produces: + ```ts + // src/pipeline/jsiInterface.ts + export interface UnreadableLine { line: number; text: string } // 1-based + /** The lines that declare an extension with an empty slot in its inheritance list: `extension :where …`, `: , P`, `P, {` (row 19). */ + export function unreadableInterfaceLines(text: string): UnreadableLine[]; + /** + * The interface ExpoModulesJSIHeaders.xcframework ships. B2 only: first removes each pair + * `@available(*, unavailable)` + `extension : where <…> : _ConstraintThatIsNotPartOfTheAPIOfThisLibrary {}`. + * Both exits: throws UnreadableInterfaceError (the guard text) when an unreadable line remains. + */ + export function readableJsiInterface(text: string, jsiVersion: string): string; + export class UnreadableInterfaceError extends Error {} + ``` +- Consumes: `writeJsiHeadersXcframework` (Task 3). The stamp keeps the raw interface's sha256. + +- [ ] **Step 1 (investigation; needs the owner's go-ahead; about 2 GB of scratch at most, deleted at the end).** + `S=/sdk56-iface`, `RNX="node /bin/rn-xtool.js"` after `npm run build` on Tasks 1–3. + `df -h ~` shows at least 5 GB free. Record everything in `$S/results.md` (never committed). + 1. **The 56 baseline.** The 56 app is the spike's (`/sdk56-spike/app56`) if it is still there, else Task 6 Step 1's create and install, done now in `/sdk56-proof/app56`. Check that `/ios` does not exist, note whether `/ios-xtool` does, then run `$RNX build` there and stop it with Ctrl-C after `✔ jsi`. Copy `/ios-xtool/jsi-out//ExpoModulesJSI.swiftinterface` (`` is the part `jsiObjectsDir()` adds) to `$S/jsi56.swiftinterface`. The adapted 0.85.3 slots are now at `/ios/build/rn-artifacts/0.85.3`. + 2. **A fresh 57 interface on the same toolchain.** Check that `../app-expo-57/ios` and `../app-expo-57/ios-xtool` do not exist. In `../app-expo-57`, `$RNX build` and stop it with Ctrl-C after `✔ jsi`. Copy its interface to `$S/jsi57.swiftinterface`. Record `swift --version`. + 3. **Compare.** `grep -nE '^extension .+ :[[:space:]]+where ' $S/jsi56.swiftinterface $S/jsi57.swiftinterface`; the two `swift-module-flags` lines; `diff` of the `_ConstraintThatIsNotPartOfTheAPIOfThisLibrary` blocks. + - **57 has the same lines:** the cause is the toolchain, and SDK 57 is broken today for anyone on Swift 6.4.1. Stop and tell the owner before going on (spec owner's ruling 1). + - **57 is clean:** the cause is in jsi 56's sources or flags; go on. + 4. **Candidate causes**, each a jsi-only rebuild into `$S/try-` with a scratch copy of `scripts/build-expo-modules-jsi.sh` at `$S/build-jsi.sh` (never the repo's), run as `RN_XTOOL_REACT_HEADERS=/ios/build/rn-artifacts/0.85.3/debug/ReactNativeHeaders.xcframework/ios-arm64/Headers RN_XTOOL_DEPS_HEADERS=/ios/build/rn-artifacts/0.85.3/debug/ReactNativeDependenciesHeaders.xcframework/ios-arm64/Headers bash $S/build-jsi.sh $S/try-`, where `` is the 56 app of item 1. After each: count the unreadable lines, keep the interface as `$S/try-.swiftinterface`, `rm -rf $S/try-`. + - (a) **How the compiler prints suppressed conformances:** list the options with `swiftc -frontend -help-hidden 2>&1 | grep -iE 'escapable|inverse|suppress|noncopyable|interface'` and try each plausible one (`-Xswiftc -Xfrontend -Xswiftc