@gfean/react-native-bundle-drop 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/BundleDrop.podspec +96 -0
  2. package/README.md +249 -9
  3. package/android/build.gradle +72 -5
  4. package/android/src/main/java/com/bundledrop/BundleDropModule.kt +137 -13
  5. package/android/src/main/java/com/bundledrop/BundleDropNativePaths.kt +43 -13
  6. package/android/src/main/java/com/bundledrop/BundleDropOtaResolver.kt +35 -0
  7. package/android/src/main/java/com/bundledrop/BundleDropStartupRecovery.kt +1117 -0
  8. package/ios/BundleDropBridge.m +27 -0
  9. package/ios/BundleDropLocator.swift +31 -15
  10. package/ios/BundleDropModule.swift +106 -3
  11. package/ios/BundleDropOtaResolver.swift +137 -29
  12. package/ios/BundleDropStartupRecovery.swift +1108 -0
  13. package/ios/BundleDropStartupRecoveryAdapter.swift +301 -0
  14. package/lib/CLI/cli.js +9 -5
  15. package/lib/CLI/scripts/doctor.js +28 -9
  16. package/lib/CLI/scripts/expo/configure-expo.js +2 -1
  17. package/lib/CLI/scripts/init-config.d.ts +2 -2
  18. package/lib/CLI/scripts/init-config.js +23 -14
  19. package/lib/CLI/scripts/login-cli.js +2 -3
  20. package/lib/CLI/scripts/native/write-runtime-identity.d.ts +19 -0
  21. package/lib/CLI/scripts/native/write-runtime-identity.js +92 -0
  22. package/lib/CLI/scripts/sight-artifacts.d.ts +9 -1
  23. package/lib/CLI/scripts/sight-artifacts.js +20 -8
  24. package/lib/CLI/scripts/sight-assets.d.ts +15 -0
  25. package/lib/CLI/scripts/sight-assets.js +71 -0
  26. package/lib/CLI/scripts/sight-cli.d.ts +3 -0
  27. package/lib/CLI/scripts/sight-cli.js +50 -4
  28. package/lib/CLI/scripts/sight-compare/assets.d.ts +6 -0
  29. package/lib/CLI/scripts/sight-compare/assets.js +73 -0
  30. package/lib/CLI/scripts/sight-compare/dependencies.d.ts +22 -0
  31. package/lib/CLI/scripts/sight-compare/dependencies.js +289 -0
  32. package/lib/CLI/scripts/sight-compare/git.d.ts +22 -0
  33. package/lib/CLI/scripts/sight-compare/git.js +116 -0
  34. package/lib/CLI/scripts/sight-compare/inspect-project.d.ts +37 -0
  35. package/lib/CLI/scripts/sight-compare/inspect-project.js +191 -0
  36. package/lib/CLI/scripts/sight-compare/metadata.d.ts +4 -0
  37. package/lib/CLI/scripts/sight-compare/metadata.js +39 -0
  38. package/lib/CLI/scripts/sight-compare/process.d.ts +22 -0
  39. package/lib/CLI/scripts/sight-compare/process.js +221 -0
  40. package/lib/CLI/scripts/sight-compare/run.d.ts +3 -0
  41. package/lib/CLI/scripts/sight-compare/run.js +290 -0
  42. package/lib/CLI/scripts/sight-compare/snapshot.d.ts +26 -0
  43. package/lib/CLI/scripts/sight-compare/snapshot.js +279 -0
  44. package/lib/CLI/scripts/sight-compare/types.d.ts +87 -0
  45. package/lib/CLI/scripts/sight-compare/types.js +2 -0
  46. package/lib/CLI/scripts/sight-ota.d.ts +18 -0
  47. package/lib/CLI/scripts/sight-ota.js +260 -0
  48. package/lib/CLI/scripts/sight-session.d.ts +9 -2
  49. package/lib/CLI/scripts/sight-session.js +58 -20
  50. package/lib/CLI/scripts/upload-cli.d.ts +12 -2
  51. package/lib/CLI/scripts/upload-cli.js +74 -11
  52. package/lib/CLI/serverUrl.d.ts +3 -0
  53. package/lib/CLI/serverUrl.js +31 -0
  54. package/lib/bundleInfo.d.ts +2 -0
  55. package/lib/bundleInfo.js +16 -1
  56. package/lib/context.js +12 -2
  57. package/lib/fs/bundlePointer.d.ts +1 -17
  58. package/lib/fs/bundlePointer.js +5 -93
  59. package/lib/install/bundleInstallShared.js +4 -4
  60. package/lib/manager/downloadAndInstall.js +25 -22
  61. package/lib/manager/reporting.d.ts +8 -1
  62. package/lib/manager/reporting.js +17 -22
  63. package/lib/manager/rollbackState.d.ts +18 -54
  64. package/lib/manager/rollbackState.js +115 -216
  65. package/lib/manager/updateCheck.js +9 -3
  66. package/lib/manager/updateState.d.ts +2 -1
  67. package/lib/manager/updateState.js +59 -6
  68. package/lib/metro.d.ts +1 -1
  69. package/lib/metro.js +4 -3
  70. package/lib/native/bundleDropNative.d.ts +62 -0
  71. package/lib/native/bundleDropNative.js +266 -1
  72. package/lib/patch-engine/installFromPatchSet.js +2 -2
  73. package/lib/runtime/service.js +29 -71
  74. package/lib/runtime-delivery/bootstrapConfig.d.ts +29 -11
  75. package/lib/runtime-delivery/bootstrapConfig.js +83 -22
  76. package/lib/runtime-delivery/manifestState.d.ts +3 -1
  77. package/lib/runtime-delivery/manifestState.js +22 -1
  78. package/lib/runtime-delivery/manifestVerifier.js +7 -1
  79. package/lib/scripts/bundle.d.ts +12 -2
  80. package/lib/scripts/bundle.js +74 -21
  81. package/lib/scripts/download-bundle.d.ts +1 -0
  82. package/lib/scripts/download-bundle.js +2 -2
  83. package/lib/scripts/resolveModule.d.ts +2 -0
  84. package/lib/scripts/resolveModule.js +5 -0
  85. package/package.json +5 -2
  86. package/plugin/xcodeBuildPhase.js +2 -1
@@ -1,7 +1,85 @@
1
+ require "digest"
2
+ require "fileutils"
1
3
  require "json"
4
+ require "open3"
5
+ require "shellwords"
6
+
7
+ bundle_drop_native_runtime_identity_resource = lambda do
8
+ return nil unless defined?(Pod::Config)
9
+
10
+ project_root = File.expand_path("..", Pod::Config.instance.installation_root.to_s)
11
+ config_path = File.join(project_root, "bundle.drop.config.js")
12
+ writer_path = File.join(
13
+ __dir__,
14
+ "lib",
15
+ "CLI",
16
+ "scripts",
17
+ "native",
18
+ "write-runtime-identity.js"
19
+ )
20
+ unless File.file?(writer_path)
21
+ raise Pod::Informative,
22
+ "Bundle Drop native runtime identity writer is missing: #{writer_path}"
23
+ end
24
+
25
+ resource_path = File.join(
26
+ "ios",
27
+ "build",
28
+ "generated",
29
+ "runtime-identity",
30
+ Digest::SHA256.hexdigest(project_root)[0, 16],
31
+ "bundle-drop-build-identity.json"
32
+ )
33
+ output_path = File.join(__dir__, resource_path)
34
+
35
+ if File.file?(config_path)
36
+ stdout, stderr, status = Open3.capture3(
37
+ ENV.fetch("NODE_BINARY", "node"),
38
+ writer_path,
39
+ "--project-root", project_root,
40
+ "--platform", "ios",
41
+ "--output", output_path
42
+ )
43
+ unless status.success?
44
+ detail = stderr.strip.empty? ? stdout.strip : stderr.strip
45
+ raise Pod::Informative,
46
+ "Bundle Drop could not generate the iOS runtime identity: #{detail}"
47
+ end
48
+
49
+ identity = JSON.parse(File.read(output_path))
50
+ return nil if identity["source"] == "expo"
51
+ unless identity["runtimeVersion"].is_a?(String) && !identity["runtimeVersion"].empty?
52
+ raise Pod::Informative, "Bundle Drop generated an invalid iOS runtime identity."
53
+ end
54
+ else
55
+ # CocoaPods evaluates the podspec before `bundle-drop login` in the documented
56
+ # fresh-install flow. Keep the resource and build phase in the Pods project so
57
+ # the first native build can replace this inert placeholder after setup.
58
+ FileUtils.mkdir_p(File.dirname(output_path))
59
+ File.write(
60
+ output_path,
61
+ JSON.generate({
62
+ "schemaVersion" => 1,
63
+ "platform" => "ios",
64
+ "source" => "unconfigured"
65
+ }) + "\n"
66
+ )
67
+ end
68
+ resource_path
69
+ end
2
70
 
3
71
  package = JSON.parse(File.read(File.join(__dir__, "package.json")))
4
72
  native_version = package["nativeVersion"] || package["version"]
73
+ native_runtime_identity_resource = bundle_drop_native_runtime_identity_resource.call
74
+ native_runtime_identity_project_root = if native_runtime_identity_resource
75
+ File.expand_path("..", Pod::Config.instance.installation_root.to_s)
76
+ end
77
+ native_runtime_identity_writer = if native_runtime_identity_resource
78
+ File.join(__dir__, "lib", "CLI", "scripts", "native", "write-runtime-identity.js")
79
+ end
80
+ native_runtime_identity_output = if native_runtime_identity_resource
81
+ File.join(__dir__, native_runtime_identity_resource)
82
+ end
5
83
 
6
84
  Pod::Spec.new do |s|
7
85
  s.name = "BundleDrop"
@@ -15,6 +93,24 @@ Pod::Spec.new do |s|
15
93
  s.source = { :git => ".git", :tag => "#{s.version}" }
16
94
 
17
95
  s.source_files = "ios/**/*.{h,m,mm,swift}", "third_party/xdelta/**/*.{c,h}"
96
+ s.resources = native_runtime_identity_resource if native_runtime_identity_resource
97
+ if native_runtime_identity_resource
98
+ # Intentionally omit output files so Xcode reruns this when a bare app builds,
99
+ # even when CocoaPods has not been reinstalled since its config changed.
100
+ s.script_phase = {
101
+ :name => "Regenerate Bundle Drop runtime identity",
102
+ :execution_position => :before_compile,
103
+ :show_env_vars_in_log => "0",
104
+ :script => <<-SCRIPT
105
+ set -e
106
+ "${NODE_BINARY:-node}" \
107
+ #{Shellwords.escape(native_runtime_identity_writer)} \
108
+ --project-root #{Shellwords.escape(native_runtime_identity_project_root)} \
109
+ --platform ios \
110
+ --output #{Shellwords.escape(native_runtime_identity_output)}
111
+ SCRIPT
112
+ }
113
+ end
18
114
  s.public_header_files = "ios/BundleDropLocator.h", "ios/BundleDropZipExtractor.h"
19
115
  s.private_header_files = "third_party/xdelta/**/*.h"
20
116
  s.pod_target_xcconfig = {
package/README.md CHANGED
@@ -43,6 +43,8 @@ runtime identity. Native changes still require a new App Store or Play Store bui
43
43
  - **Runtime gating** — updates only reach compatible native binaries.
44
44
  - **Observability metadata** — bundle hashes and source maps keep crash reports attributable to the correct release.
45
45
  - **CI/CD support** — upload with a Personal Access Token from any pipeline.
46
+ - **Bundle Drop Sight** — inspect JavaScript bundle sizes locally, including
47
+ working-tree comparisons against a Git baseline.
46
48
 
47
49
  ## Compatibility
48
50
 
@@ -87,6 +89,219 @@ cd ios && pod install
87
89
  React Native autolinking handles the package on both platforms. The setup command
88
90
  adds the app-entry integration that allows a Release build to start an installed OTA.
89
91
 
92
+ ## Bundle Drop Sight
93
+
94
+ Sight analyzes production JavaScript bundles and emitted assets in your browser. It
95
+ does not require a Bundle Drop account, OTA project configuration, login, or native
96
+ integration. Run it from the app directory containing `package.json`:
97
+
98
+ ```bash
99
+ npx bundle-drop sight --platform android
100
+ npx bundle-drop sight --compare main --platform android
101
+ npx bundle-drop sight --compare origin/main --fetch --platform ios
102
+ ```
103
+
104
+ The first command analyzes the current app using its installed dependencies and
105
+ includes emitted assets through the automatic CLI handoff.
106
+ `--compare` builds both an explicit Git baseline and a captured copy of your current
107
+ working tree. Both builds run locally, including when the baseline is a remote
108
+ tracking branch. Sight compares **raw UTF-8 bytes in minified JavaScript** and uses
109
+ source maps to attribute changes to packages and files. Both CLI modes include a
110
+ **Bundled assets** breakdown for files emitted by the same Metro/Expo build, such as
111
+ images and fonts. Assets do not change the JavaScript totals or treemap.
112
+
113
+ **Bundle Drop OTA size** measures a locally generated full OTA archive using Bundle Drop's
114
+ canonical packaging. Each revision uses its own JavaScript engine configuration:
115
+ Hermes is compiled with project-local tooling when enabled. JavaScript attribution
116
+ and raw asset sizes remain separate; they are not bytecode attribution.
117
+
118
+ Measurement adds compilation and archive compression after the JavaScript build, once
119
+ per side in a comparison. Expo's Hermes path also performs a separate bytecode
120
+ export to preserve its upload-specific minification behavior. It requires a resolvable app/runtime identity. When that
121
+ identity or required compiler is unavailable, Sight keeps the JavaScript and asset
122
+ analysis and marks the OTA measurement unavailable with a reason. It never fills in
123
+ an estimated archive size. Comparing this metric requires Bundle Drop to be configured
124
+ on both branches with a resolvable app/runtime identity. The archive describes the selected Sight entry and build
125
+ environment; upload overrides or different inputs can produce another size.
126
+
127
+ Asset sizes count each emitted output file once, including emitted density variants.
128
+ Identical contents at different output paths count separately; a changed hash at the
129
+ same path is a change even when the byte size is unchanged. Only emitted files are
130
+ counted, not every asset in the repository. Native-only resources and network-loaded
131
+ assets are outside this measurement. The OTA archive includes delivery metadata and asset
132
+ manifests, and excludes source maps. It is not APK/IPA size. File size changes do
133
+ not measure startup time or memory use.
134
+
135
+ No native app build is needed for asset analysis or comparison. The existing JavaScript bundling
136
+ step emits the files into private temporary directories; the CLI records relative
137
+ output paths, byte lengths, and SHA-256 hashes, then removes the emitted asset copies.
138
+ Only the inventory is passed to Sight, with no image previews or binary asset uploads.
139
+ This collection code stays in the CLI and adds no runtime dependencies or mobile SDK
140
+ code.
141
+
142
+ The CLI transfers the generated files to Sight through a short-lived loopback
143
+ session. Source code, bundles, source maps, and comparison metadata are not uploaded
144
+ to Bundle Drop servers. Loading the Sight web page still needs browser access to
145
+ `bundledrop.app`.
146
+
147
+ ### Comparison options
148
+
149
+ | Option | Behavior |
150
+ | --- | --- |
151
+ | `--compare <ref>` | Resolve a branch, tag, or commit to an immutable baseline commit before building. |
152
+ | `--fetch` | Refresh the explicitly named remote branch, such as `origin/main`, using ordinary Git credentials. Requires `--compare`. |
153
+ | `--platform ios\|android` | Compare one platform per invocation. If ambiguous, interactive use prompts; noninteractive use requires the flag. |
154
+ | `--project-type bare\|expo` | Override project detection consistently for both sides. |
155
+ | `--entry-file <path>` | Choose an app-relative entry file that must exist in both snapshots. |
156
+ | `--include <path>` | Copy an extra local file or directory identically into both snapshots; repeat for multiple inputs. |
157
+ | `--no-open` | Keep the generated files and print manual browser instructions. |
158
+ | `--keep` | Keep the comparison files after a successful browser transfer. |
159
+ | `--output <path>` | Write persistent output to an empty directory. |
160
+
161
+ Without `--fetch`, Sight uses locally available refs and does not contact a Git
162
+ remote. `main` is never silently substituted with `origin/main`. Explicit refresh
163
+ requires a configured remote branch; use normal Git commands first to obtain a
164
+ missing tag, commit, or additional shallow history. Sight neither requests nor
165
+ stores repository credentials.
166
+
167
+ ### What each side builds
168
+
169
+ The current snapshot contains tracked working-tree contents, including uncommitted
170
+ edits and deletions, plus nonignored untracked files. Ignored inputs such as local
171
+ environment files are excluded unless explicitly included:
172
+
173
+ ```bash
174
+ npx bundle-drop sight --compare main --platform android \
175
+ --include .env.production --include local-build-config
176
+ ```
177
+
178
+ Included paths must stay inside the repository. They cannot overwrite files
179
+ tracked on either side or supply dependency manifests, lockfiles, or installed
180
+ dependencies. The same captured contents are added to both sides, so the baseline
181
+ remains a comparison under the same explicitly supplied local configuration.
182
+
183
+ Sight creates private temporary Git worktrees for the two builds. Both have a
184
+ detached `HEAD`: baseline points at the resolved baseline commit, and current
185
+ points at your original `HEAD` with captured working-tree files overlaid. Your
186
+ original staging partition is not reproduced; scripts that distinguish staged
187
+ from unstaged changes, or depend on an attached branch name, may behave differently.
188
+ Sight does not switch, stash, reset, or stage your original checkout.
189
+
190
+ The private repository has independent object storage and preserves the captured
191
+ local branch/tag/remote-tracking refs and available history. `git rev-parse HEAD`
192
+ and ancestry queries use each side's own commit. `git describe` evaluates the
193
+ captured tags from that commit; these are today's locally available refs, not
194
+ their historical state at the baseline date. Missing shallow history or tags may
195
+ change its output, and Sight does not fetch them implicitly. Branch-name queries
196
+ observe detached HEAD; the original branch label is metadata only.
197
+
198
+ `git describe --dirty` reflects each private worktree, including explicit includes
199
+ and build-script changes. Original dirty status is recorded separately. Builds
200
+ depending on attached branches or staging partitions must accommodate these
201
+ semantics through their existing configuration/environment. Sight verifies pinned
202
+ HEADs and refs around build phases and rejects mutations that invalidate provenance.
203
+ It rechecks captured files, modes, symlinks, HEAD, and index for observed concurrent
204
+ changes; the copy is not an atomic filesystem snapshot.
205
+
206
+ Both sides use the same Node executable, platform, production/minification settings,
207
+ and logical entrypoint. Each revision retains its own dependencies and bundler
208
+ configuration. Sight records framework/package-manager versions and warns when
209
+ relevant inputs differ. A framework upgrade or configuration change can legitimately
210
+ affect the result. Required environment variables must be available to both builds;
211
+ there is no automatic fallback from a failed build to the other revision's output.
212
+
213
+ ### Dependencies and supported repository layouts
214
+
215
+ Comparison installs fresh dependencies for each side from its own lockfile. It
216
+ supports npm, pnpm, Yarn Classic, and modern Yarn with `nodeLinker: node-modules`.
217
+ An exact `packageManager` declaration must match the available executable; tracked
218
+ `yarnPath` configurations are honored. Without a declaration, a unique lockfile
219
+ family selects the available manager and its actual version is recorded. Sight
220
+ does not automatically download package-manager binaries or change a lockfile to
221
+ make installation succeed.
222
+
223
+ Dependency installation can access package registries and execute project lifecycle
224
+ scripts. Existing script policies are preserved. For declared `engines.node` ranges,
225
+ Sight uses the installed `npm` executable to check a temporary dependency-free
226
+ manifest with an offline, script-disabled dry run before the real installs. This
227
+ check also requires npm when the project uses Yarn or pnpm. Build/configuration
228
+ scripts execute as ordinary local processes; the temporary worktrees are not a
229
+ security sandbox for untrusted project code.
230
+
231
+ Apps in a single npm, Yarn, or pnpm workspace root can use other packages inside
232
+ the same Git repository. Installation runs at the workspace root; bundling runs
233
+ from the app directory. Nested/ambiguous workspace roots, nested app lockfiles,
234
+ external local dependencies or symlinks, Bun, and Plug'n'Play installations are not
235
+ supported. npm workspaces require a v2 or newer lockfile. Unresolved Git conflicts,
236
+ sparse/partial clones, required Git submodules, Git LFS/checkout filters, and tracked
237
+ `node_modules` are also unsupported. There is no comparison build or dependency-tree
238
+ cache in this version.
239
+
240
+ Actual workspace frozen installs have been verified on macOS arm64 with Node
241
+ 22.13.0 using npm 10.9.2, pnpm 11.24.0, Yarn 1.22.22, and Yarn 3.8.3. These installer
242
+ checks cover a registry dependency, a local workspace dependency, lifecycle scripts,
243
+ and unchanged manifests/lockfiles. Real comparisons were also verified with npm
244
+ 10.9.2, React Native 0.83.1, and Expo 55.0.0: dirty source capture, package additions,
245
+ identical inputs, and automatic browser attribution after source cleanup.
246
+ An Expo Router 55.0.18 app also passed a real comparison using `expo-router/entry`.
247
+ Windows/Linux hosts and full framework builds with pnpm or Yarn remain unverified;
248
+ the installer checks alone do not establish those combinations.
249
+
250
+ ### Keeping files and opening Sight manually
251
+
252
+ ```bash
253
+ npx bundle-drop sight --platform android --no-open --output ./sight-analysis
254
+ npx bundle-drop sight --compare main --platform android \
255
+ --no-open --output ./sight-comparison
256
+ ```
257
+
258
+ Single analysis keeps a bundle/source-map pair and `analysis-assets.json`, a local
259
+ record of emitted paths, sizes, hashes, and the exact bundle/map hashes. The automatic
260
+ CLI handoff verifies this binding before including assets in the analysis.
261
+
262
+ Comparison output contains `baseline/` and `current/` bundle/source-map pairs plus
263
+ `comparison.json` and `comparison-assets.json` as local records. Automatic CLI
264
+ loading verifies these files and includes Git labels, build context, and asset
265
+ sizes. The browser does not expose metadata or inventory upload controls.
266
+
267
+ For a manual JavaScript-only comparison, open
268
+ [Bundle Drop Sight](https://bundledrop.app/sight), select Compare, and attach the
269
+ four bundle/map files. Manual Analyze still takes one bundle and its matching map;
270
+ manual Compare still takes two pairs. Neither requires the Bundle Drop SDK or extra
271
+ JSON files. Git labels and asset sizes appear only through the CLI handoff. Changing
272
+ a file after a CLI handoff clears its comparison context.
273
+
274
+ Comparison metadata remains limited to 64 KiB. Each asset inventory is limited to
275
+ 4 MiB and 10,000 files per build; oversized inventories fail explicitly
276
+ instead of producing partial totals. Inventory paths are output-relative and are
277
+ never opened by the browser.
278
+
279
+ Temporary worktrees and dependencies are removed after success, failure, or
280
+ cancellation. Completed files from either CLI mode are retained when browser handoff
281
+ fails; the CLI prints their location, and comparisons also print the diagnostics
282
+ directory. `--keep`, `--no-open`, and `--output` retain the requested artifacts,
283
+ including the local asset record. A failure before complete artifacts
284
+ exist removes owned temporary output; explicitly requested output directories are
285
+ kept for inspection.
286
+
287
+ The metadata contains local temporary source roots so unchanged source maps remain
288
+ attributable after cleanup. Sight excludes those roots from displayed/exported
289
+ provenance and analytics. Manual file loading uses ordinary JavaScript comparison
290
+ behavior without the CLI source-path context.
291
+
292
+ Removal failures report the owned directory for manual recovery. An uncatchable
293
+ termination, such as a forced process kill or power loss, can leave temporary
294
+ `bundle-drop-sight-*` directories. After confirming the invocation and its build
295
+ processes have stopped, remove only those reported/identified temporary directories;
296
+ keep completed comparison output if it is still needed.
297
+
298
+ On macOS/Linux, Sight stops ordinary child process groups before removing the
299
+ worktrees, including background children left after a command exits. On Windows,
300
+ cancellation uses `taskkill` for the active process tree, but this version has no
301
+ Job Object containment: background descendants can survive if their parent has
302
+ already exited. Scripts that deliberately detach into a separate process group
303
+ also fall outside process-group cleanup.
304
+
90
305
  ## First-Time Setup
91
306
 
92
307
  Run these commands from your app's project root:
@@ -125,13 +340,14 @@ npx bundle-drop doctor
125
340
  Apps upgrading from an inline `runtimeDelivery` block or a direct Metro alias should
126
341
  remove that stale block and run `npx bundle-drop init` once to install the
127
342
  package-managed Metro wrapper. Inline delivery data is ignored: the validated
128
- generated bootstrap is the sole trust source. After that one-time migration, `sync`
343
+ runtime-delivery lockfile is the sole trust source. After that one-time migration, `sync`
129
344
  is the narrow command for refreshing trust data.
130
345
 
131
- The generated bootstrap is not a secret and should be committed. Setup keeps the
346
+ The runtime-delivery lockfile is not a secret and should be committed. Setup keeps the
132
347
  generated Metro wrapper, build receipts, and other transient `.bundle-drop` files
133
- ignored while allowing `.bundle-drop/runtime-delivery.generated.json` into source
134
- control.
348
+ ignored while allowing `.bundle-drop/runtime-delivery.lock.json` into source
349
+ control. Projects with the former `runtime-delivery.generated.json` filename remain
350
+ readable; run `bundle-drop sync` to migrate and remove that legacy file.
135
351
 
136
352
  ### Manual setup without AI planning
137
353
 
@@ -189,9 +405,9 @@ npx bundle-drop sync
189
405
  npx bundle-drop doctor
190
406
  ```
191
407
 
192
- `sync` creates `.bundle-drop/runtime-delivery.generated.json`, recreates it if it or
408
+ `sync` creates `.bundle-drop/runtime-delivery.lock.json`, recreates it if it or
193
409
  the entire `.bundle-drop` directory was deleted, and repairs the corresponding
194
- `.gitignore` rules. The bootstrap contains public identity and verification material,
410
+ `.gitignore` rules. The lockfile contains public identity and verification material,
195
411
  not secrets, so commit it with the application.
196
412
 
197
413
  ## Initialize the Runtime
@@ -320,6 +536,30 @@ example, an iOS-only native change should bump `runtimeVersion.ios`; Android can
320
536
  its existing value. This makes the compatibility boundary explicit and prevents an
321
537
  update from reaching a binary that cannot run it.
322
538
 
539
+ ## Native Startup Recovery
540
+
541
+ Bundle Drop records every OTA startup attempt in native storage before React Native
542
+ receives the bundle path. If an attempt does not reach its configured health boundary,
543
+ the next distinct app launch counts it as incomplete. The candidate is retried until
544
+ `rollback.maxCrashCount` is reached, then quarantined locally and replaced with the
545
+ previous native-proven healthy OTA bundle. If that bundle is missing, corrupt,
546
+ incompatible, or locally revoked, startup falls back to the bundle embedded in the app.
547
+
548
+ Automatic health waits for React content to appear and then applies
549
+ `rollback.healthyAfterSec`. Apps with a stronger readiness boundary can opt into
550
+ `healthCheckMode: 'manual'` and call `BundleDrop.reportHealthy()` after hydration,
551
+ migrations, authentication bootstrap, or navigation setup completes. Health is committed
552
+ against the exact native launch attempt, so a delayed callback from an older React runtime
553
+ cannot approve a newer launch.
554
+
555
+ Recovery is local and offline; it never waits for a network request during startup. With
556
+ `maxCrashCount: 0`, launch-health counting and automatic crash-loop rollback are disabled,
557
+ while integrity, runtime compatibility, quarantine, and locally persisted revocation checks
558
+ still apply. Native startup recovery requires a binary built with the corresponding SDK
559
+ `nativeVersion`; it cannot be added to an older installed binary through OTA JavaScript.
560
+ Crashes after an attempt is healthy do not trigger this rollback path and should use normal
561
+ crash reporting plus fix-forward or explicit rollback controls.
562
+
323
563
  ## Managed Runtime Delivery
324
564
 
325
565
  Runtime delivery is package-managed. `bundle.drop.config.js` stays focused on
@@ -330,14 +570,14 @@ a delivery-mode switch.
330
570
  `bundle-drop login` and `bundle-drop init` synchronize the trust bootstrap during
331
571
  setup. `bundle-drop sync` performs the same narrow operation later for repair or key
332
572
  rotation. Each command validates authenticated project credentials and writes the
333
- identity-bound `.bundle-drop/runtime-delivery.generated.json`. Metro confirms that
573
+ identity-bound `.bundle-drop/runtime-delivery.lock.json`. Metro confirms that
334
574
  the bootstrap belongs to the same server, organization, and project before merging
335
575
  it into the runtime module. Malformed, copied, unsupported, or private-key-bearing
336
576
  data is rejected.
337
577
 
338
578
  Older apps with an inline `runtimeDelivery` block keep their ordinary project
339
579
  configuration, but the inline block is ignored and should be removed during
340
- migration. Only the identity-bound generated bootstrap can enable managed delivery.
580
+ migration. Only the identity-bound runtime-delivery lockfile can enable managed delivery.
341
581
  If the server explicitly disables delivery for a project, synchronization removes a
342
582
  stale bootstrap and the SDK continues through the compatible `/ota/resolve` path.
343
583
 
@@ -529,7 +769,7 @@ Import the runtime API from `@gfean/react-native-bundle-drop`.
529
769
  | `BundleDrop.init(options)` | Initialize the runtime for the app process. |
530
770
  | `BundleDrop.setChannel(name)` / `setChannel` | Change the active channel for singleton actions. |
531
771
  | `BundleDrop.getChannelName()` / `getChannelName` | Read the active channel. |
532
- | `BundleDrop.reportHealthy()` / `reportHealthy` | Mark the running OTA candidate healthy for this device. |
772
+ | `BundleDrop.reportHealthy()` / `reportHealthy` | In manual health mode, ask native recovery to mark the exact running OTA attempt healthy. |
533
773
 
534
774
  **`BundleDrop.init(options)`**
535
775
 
@@ -1,3 +1,19 @@
1
+ import javax.inject.Inject
2
+ import org.gradle.process.ExecOperations
3
+
4
+ abstract class BundleDropNativeIdentityCommandExecutor {
5
+ @Inject
6
+ abstract ExecOperations getExecOperations()
7
+
8
+ void execute(File workingDirectory, String executable, List<?> arguments) {
9
+ execOperations.exec { spec ->
10
+ spec.workingDir workingDirectory
11
+ spec.executable executable
12
+ spec.args arguments
13
+ }.assertNormalExitValue()
14
+ }
15
+ }
16
+
1
17
  buildscript {
2
18
  ext.getExtOrDefault = {name ->
3
19
  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['BundleDrop_' + name]
@@ -17,7 +33,13 @@ buildscript {
17
33
 
18
34
 
19
35
  apply plugin: "com.android.library"
20
- apply plugin: "kotlin-android"
36
+ // AGP 9 ships built-in Kotlin support and registers the `kotlin` extension
37
+ // itself. Applying the Kotlin plugin on top of it fails configuration with
38
+ // "Cannot add extension with name 'kotlin'". Only apply it when nothing has
39
+ // registered that extension yet.
40
+ if (project.extensions.findByName('kotlin') == null) {
41
+ apply plugin: "kotlin-android"
42
+ }
21
43
 
22
44
  if (project.hasProperty("standalone")) {
23
45
  apply plugin: "jacoco"
@@ -76,10 +98,6 @@ android {
76
98
  targetCompatibility JavaVersion.VERSION_1_8
77
99
  }
78
100
 
79
- kotlinOptions {
80
- jvmTarget = "1.8"
81
- }
82
-
83
101
  externalNativeBuild {
84
102
  cmake {
85
103
  path "src/main/cpp/CMakeLists.txt"
@@ -88,6 +106,49 @@ android {
88
106
  }
89
107
  }
90
108
 
109
+ if (!project.hasProperty("standalone") && rootProject.findProject(":bundledrop-expo") == null) {
110
+ def bundleDropProjectRoot = rootProject.projectDir.parentFile.canonicalFile
111
+ def bundleDropConfigFile = new File(bundleDropProjectRoot, "bundle.drop.config.js")
112
+ if (bundleDropConfigFile.isFile()) {
113
+ def bundleDropIdentityWriter = file(
114
+ "../lib/CLI/scripts/native/write-runtime-identity.js"
115
+ ).canonicalFile
116
+ if (!bundleDropIdentityWriter.isFile()) {
117
+ throw new GradleException(
118
+ "Bundle Drop native runtime identity writer is missing: ${bundleDropIdentityWriter}"
119
+ )
120
+ }
121
+ def bundleDropGeneratedAssets = file("${buildDir}/generated/bundleDropIdentity/assets")
122
+ def bundleDropIdentityOutput = new File(
123
+ bundleDropGeneratedAssets,
124
+ "bundle-drop/build-identity.json"
125
+ )
126
+ android.sourceSets.main.assets.srcDir(bundleDropGeneratedAssets)
127
+ def bundleDropCommandExecutor = objects.newInstance(
128
+ BundleDropNativeIdentityCommandExecutor
129
+ )
130
+ def generateBundleDropNativeRuntimeIdentity = tasks.register(
131
+ "generateBundleDropNativeRuntimeIdentity"
132
+ ) { task ->
133
+ task.inputs.file(bundleDropConfigFile)
134
+ task.inputs.file(bundleDropIdentityWriter)
135
+ task.outputs.file(bundleDropIdentityOutput)
136
+ task.doLast {
137
+ def nodeBinary = System.getenv("NODE_BINARY") ?: "node"
138
+ bundleDropCommandExecutor.execute(bundleDropProjectRoot, nodeBinary, [
139
+ bundleDropIdentityWriter.path,
140
+ "--project-root", bundleDropProjectRoot.path,
141
+ "--platform", "android",
142
+ "--output", bundleDropIdentityOutput.path
143
+ ])
144
+ }
145
+ }
146
+ tasks.named("preBuild").configure { task ->
147
+ task.dependsOn(generateBundleDropNativeRuntimeIdentity)
148
+ }
149
+ }
150
+ }
151
+
91
152
  afterEvaluate {
92
153
  tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { kotlinTask ->
93
154
  def javaTask = tasks.findByName(kotlinTask.name.replace("Kotlin", "JavaWithJavac"))
@@ -200,6 +261,12 @@ if (project.hasProperty("standalone")) {
200
261
  limit { counter = "LINE"; minimum = 0.90 }
201
262
  limit { counter = "BRANCH"; minimum = 0.85 }
202
263
  }
264
+ rule {
265
+ element = "CLASS"
266
+ includes = ["com.bundledrop.BundleDropStartupRecoveryController"]
267
+ limit { counter = "LINE"; minimum = 0.90 }
268
+ limit { counter = "BRANCH"; minimum = 0.70 }
269
+ }
203
270
  rule {
204
271
  element = "CLASS"
205
272
  includes = ["com.bundledrop.BundleDropFileOps"]