react-native-debug-toolkit 3.3.3 → 3.3.4

package/README.md

@@ -77,11 +77,44 @@ In the app, open Debug Panel -> `DevConnect` -> `Send Once` or `Start Live Sync`
 
 DevConnect auto-detects simulator/emulator and uses local host settings automatically. On real devices, enter your computer IP to connect.
 
-For Remote JS Bundle, run Metro on your computer, enter computer IP and Metro port in `DevConnect`, then tap `Use Metro Bundle`. DevConnect persists the host and hot-reloads from Metro.
+### Embedded Debug Bundle
+
+Debug builds need an embedded JS bundle for cold start when Metro is off.
+
+Bare React Native:
+
+```bash
+npx debug-toolkit setup-bundle
+git diff
+git commit -am "chore: enable debug bundle embedding"
+```
+
+Expo dev-client:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      ["react-native-debug-toolkit/dev-client", { "embedBundle": true }]
+    ]
+  }
+}
+```
+
+Verify built artifacts:
+
+```bash
+npx debug-toolkit doctor-bundle --platform ios --app path/to/App.app
+npx debug-toolkit doctor-bundle --platform android --apk path/to/app-debug.apk
+```
+
+After setup, build machines run normal Xcode, Gradle, React Native, or EAS commands. Do not run a separate mutation command on every build.
+
+For Remote JS Bundle, run Metro on your computer, enter computer IP and Metro port in `DevConnect`, then tap `Use Metro Bundle`. DevConnect persists the host and hot-reloads from Metro. Use **Reset** to go back to the embedded bundle.
 
 > **Debug builds only.** Metro host switching works in Debug builds. Release builds load the embedded bundle and the controls are disabled (`release: disabled` badge).
 
-**iOS — no AppDelegate changes required.** On install, DevConnect hooks `RCTBundleURLProvider` so the app **cold-starts from the embedded `main.jsbundle`** and only connects to Metro after you apply a host in the panel (fixes Expo `.expo/.virtual-metro-entry` red screens when Metro is off). Use **Reset** to go back to the embedded bundle.
+**iOS — no AppDelegate changes required.** On install, DevConnect hooks `RCTBundleURLProvider` so the app **cold-starts from the embedded `main.jsbundle`** and only connects to Metro after you apply a host in the panel (fixes Expo `.expo/.virtual-metro-entry` red screens when Metro is off).
 
 The IP and ports are persisted through AsyncStorage when installed, or through the native module after rebuild.
 

package/README.zh-CN.md

@@ -77,11 +77,44 @@ App 内打开 Debug Panel -> `DevConnect` -> `Send Once` 或 `Start Live Sync`
 
 DevConnect 自动识别模拟器/真机，模拟器下自动使用本机 Metro/daemon 地址。真机需输入电脑 IP 地址。
 
-Remote JS Bundle：先在电脑启动 Metro，在 `DevConnect` 输入电脑 IP 和 Metro 端口，然后点 `Use Metro Bundle`。DevConnect 会持久化 host 并从 Metro 热重载。
+### Debug 包内置 Bundle
+
+Debug 包要在 Metro 关闭时冷启动，必须内置 JS bundle。
+
+Bare React Native:
+
+```bash
+npx debug-toolkit setup-bundle
+git diff
+git commit -am "chore: enable debug bundle embedding"
+```
+
+Expo dev-client:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      ["react-native-debug-toolkit/dev-client", { "embedBundle": true }]
+    ]
+  }
+}
+```
+
+验证产物：
+
+```bash
+npx debug-toolkit doctor-bundle --platform ios --app path/to/App.app
+npx debug-toolkit doctor-bundle --platform android --apk path/to/app-debug.apk
+```
+
+setup 后配置进仓库，打包机继续跑正常 Xcode、Gradle、React Native 或 EAS 命令。不要每次打包再跑额外修改命令。
+
+Remote JS Bundle：先在电脑启动 Metro，在 `DevConnect` 输入电脑 IP 和 Metro 端口，然后点 `Use Metro Bundle`。DevConnect 会持久化 host 并从 Metro 热重载。点 **Reset** 可回到内置 bundle。
 
 > **仅 Debug 包可用。** Release 包控件会显示 `release: disabled` 并禁用。
 
-**iOS — 无需改 AppDelegate。** 安装本库后会 hook `RCTBundleURLProvider`：**未配置 IP 时冷启动走内置 `main.jsbundle`**，只有在面板里应用 host 后才连 Metro（可避免 Metro 未开时的 `.expo/.virtual-metro-entry` 红屏）。点 **Reset** 可回到内置 bundle。
+**iOS — 无需改 AppDelegate。** 安装本库后会 hook `RCTBundleURLProvider`：**未配置 IP 时冷启动走内置 `main.jsbundle`**，只有在面板里应用 host 后才连 Metro（可避免 Metro 未开时的 `.expo/.virtual-metro-entry` 红屏）。
 
 IP 和端口会通过 AsyncStorage 持久化；如果没装 AsyncStorage，则在重建后通过本库原生模块持久化。
 

package/app.plugin.js

@@ -0,0 +1,51 @@
+'use strict';
+
+function markTestConfig(config) {
+  config.extra = config.extra || {};
+  config.extra.reactNativeDebugToolkit = {
+    ...(config.extra.reactNativeDebugToolkit || {}),
+    embedBundle: true,
+  };
+  return config;
+}
+
+function loadConfigPlugins() {
+  try {
+    return require('@expo/config-plugins');
+  } catch {
+    throw new Error(
+      'react-native-debug-toolkit/dev-client requires @expo/config-plugins during Expo prebuild.',
+    );
+  }
+}
+
+function withDebugToolkitDevClient(config, props = {}) {
+  if (!props.embedBundle) {
+    return config;
+  }
+
+  if (props._testOnly) {
+    return markTestConfig(config);
+  }
+
+  const { withDangerousMod } = loadConfigPlugins();
+  const { setupIosBundle } = require('./scripts/bundle/ios');
+  const { setupAndroidBundle } = require('./scripts/bundle/android');
+
+  config = withDangerousMod(config, ['ios', async (modConfig) => {
+    setupIosBundle({
+      cwd: modConfig.modRequest.projectRoot,
+      iosTarget: props.iosTarget,
+    });
+    return modConfig;
+  }]);
+
+  config = withDangerousMod(config, ['android', async (modConfig) => {
+    setupAndroidBundle({ cwd: modConfig.modRequest.projectRoot });
+    return modConfig;
+  }]);
+
+  return config;
+}
+
+module.exports = withDebugToolkitDevClient;

package/bin/debug-toolkit.js

@@ -27,21 +27,19 @@ function hasHelpFlag(args) {
 function printHelp() {
   process.stderr.write(
     'Usage: debug-toolkit [--host 0.0.0.0] [--port 3799] [--token dev-token] [--store ~/.react-native-debug-toolkit/daemon-devices.json] [--daemon-only]\n'
-  + '       debug-toolkit embed [--platform ios|android] [--undo] [--yes]\n'
+  + '       debug-toolkit setup-bundle [--platform ios|android] [--undo] [--check] [--ios-target <name>]\n'
+  + '       debug-toolkit doctor-bundle --platform ios --app <path-to.app>\n'
+  + '       debug-toolkit doctor-bundle --platform android --apk <path-to.apk>\n'
   + '\n'
   + 'Starts the debug toolkit: daemon (HTTP + Web Console) and MCP stdio server.\n'
   + '\n'
   + 'Commands:\n'
-  + '  embed           Embed JS bundle in debug builds (run in host app root)\n'
-  + '\n'
-  + 'Embed options:\n'
-  + '  --platform <p>  Target platform: ios or android (default: both)\n'
-  + '  --undo          Remove embed injections\n'
-  + '  --yes           Skip confirmations (CI/EAS)\n'
+  + '  setup-bundle    Persistently configure host app debug builds to embed JS bundle\n'
+  + '  doctor-bundle   Verify source config or built app package contains embedded bundle\n'
   + '\n'
   + 'Daemon options:\n'
   + '  --host <addr>   Host to bind (default: 0.0.0.0)\n'
-    + '  --port <port>   Port to bind (default: 3799)\n'
+  + '  --port <port>   Port to bind (default: 3799)\n'
   + '  --token <str>   Auth token for daemon endpoints\n'
   + '  --store <path>  Device log store path\n'
   + '  --daemon-only   Start only the HTTP daemon and Web Console\n'
@@ -66,10 +64,13 @@ async function main() {
     return;
   }
 
-  // Route embed subcommand
-  if (args[0] === 'embed') {
-    const { main: embedMain } = require('../scripts/embed');
-    return embedMain(args.slice(1));
+  if (['setup-bundle', 'doctor-bundle', 'embed'].includes(args[0])) {
+    const { runBundleCli } = require('../scripts/bundle/cli');
+    const code = await runBundleCli(args);
+    if (code !== 0) {
+      process.exitCode = code;
+    }
+    return;
   }
 
   const host = readOption(args, '--host', process.env.DEBUG_TOOLKIT_DAEMON_HOST || DEFAULT_HOST);

package/dev-client.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./app.plugin');

package/ios/DebugToolkitDevConnect.mm

@@ -15,9 +15,10 @@
 // Debug-only Metro host switching — zero host-app native changes required.
 //
 // RN/Expo Debug templates call jsBundleURLForBundleRoot:fallbackURLProvider:, which consults
-// -packagerServerHostPort (guessPackagerHost on simulator when Metro is running). We hook:
-//   1. jsBundleURLForBundleRoot:fallbackURLProvider: — no DevConnect host → main.jsbundle first.
-//   2. packagerServerHostPort — no DevConnect host → nil (block auto-discovered localhost:8081).
+// -packagerServerHostPort (guessPackagerHost on simulator when Metro is running). We only hook
+// jsBundleURLForBundleRoot:fallbackURLProvider: so no DevConnect host starts from main.jsbundle.
+// Persisted DevConnect hosts still flow through RCTBundleURLProvider, preserving RN's reachability
+// and fallback behavior when a saved Metro host is stale.
 //
 // Optional: host apps may call DebugToolkitMetroBundleURL() from bundleURL() for explicit control.
 
@@ -26,7 +27,6 @@ static NSString *const kBundleRoot = @"index";
 static NSString *const kExpoVirtualMetroEntry = @".expo/.virtual-metro-entry";
 static NSString *const kMetroHostKey = @"_devconnect_metro_host";
 
-static BOOL gPackagerHookInstalled = NO;
 static BOOL gBundleRootHookInstalled = NO;
 
 static NSURL *(*gOrigJsBundleURLForBundleRootWithFallback)(id, SEL, NSString *, NSURL * _Nonnull (^)(void));
@@ -97,17 +97,6 @@ static NSURL *DevConnectMetroURLForPersistedHost(void)
   return [settings jsBundleURLForBundleRoot:DevConnectMetroBundleRoot()];
 }
 
-/// When no DevConnect host: block guessPackagerHost (simulator often has Metro on :8081).
-static NSString *replacement_packagerServerHostPort(id self, SEL _cmd)
-{
-  NSString *host = DevConnectPersistedMetroHost();
-  if (host.length == 0) {
-    return nil;
-  }
-  [(RCTBundleURLProvider *)self setJsLocation:host];
-  return host;
-}
-
 /// Primary hook: return embedded main.jsbundle before RN/Expo tries Metro / virtual-metro-entry.
 static NSURL *replacement_jsBundleURLForBundleRoot_fallback(
     id self, SEL _cmd, NSString *bundleRoot, NSURL * _Nonnull (^fallbackURLProvider)(void))
@@ -127,25 +116,6 @@ static NSURL *replacement_jsBundleURLForBundleRoot_fallback(
   return fallbackURLProvider ? fallbackURLProvider() : nil;
 }
 
-static void DebugToolkitInstallPackagerHook(Class cls)
-{
-  if (gPackagerHookInstalled) {
-    return;
-  }
-  Method method = class_getInstanceMethod(cls, @selector(packagerServerHostPort));
-  if (!method) {
-    NSLog(@"[DevConnect] packagerServerHostPort not found");
-    return;
-  }
-  IMP replacement = (IMP)replacement_packagerServerHostPort;
-  if (method_getImplementation(method) == replacement) {
-    gPackagerHookInstalled = YES;
-    return;
-  }
-  method_setImplementation(method, replacement);
-  gPackagerHookInstalled = YES;
-}
-
 static void DebugToolkitInstallBundleRootHook(Class cls)
 {
   if (gBundleRootHookInstalled) {
@@ -170,7 +140,7 @@ static void DebugToolkitInstallBundleRootHook(Class cls)
 
 static void DebugToolkitInstallAllHooks(void)
 {
-  if (gBundleRootHookInstalled && gPackagerHookInstalled) {
+  if (gBundleRootHookInstalled) {
     return;
   }
 
@@ -181,15 +151,12 @@ static void DebugToolkitInstallAllHooks(void)
   }
 
   DebugToolkitInstallBundleRootHook(cls);
-  DebugToolkitInstallPackagerHook(cls);
 
   static BOOL didLogOutcome = NO;
-  if (!didLogOutcome && (gBundleRootHookInstalled || gPackagerHookInstalled)) {
+  if (!didLogOutcome) {
     didLogOutcome = YES;
     if (DevConnectEmbeddedFirstHooksActive()) {
-      NSLog(@"[DevConnect] embedded-first hooks active (bundleRoot=%@ packager=%@)",
-            gBundleRootHookInstalled ? @"Y" : @"N",
-            gPackagerHookInstalled ? @"Y" : @"N");
+      NSLog(@"[DevConnect] embedded-first hook active");
     } else {
       NSLog(@"[DevConnect] embedded-first hooks FAILED — rebuild / check React linkage");
     }
@@ -365,7 +332,7 @@ RCT_EXPORT_METHOD(getDiagnostics:(RCTPromiseResolveBlock)resolve
     @"isDebugBuild": @(isDebug),
     @"hasEmbeddedBundle": @(DebugToolkitEmbeddedBundleURL() != nil),
     @"embeddedFirstHookInstalled": @(DevConnectEmbeddedFirstHooksActive()),
-    @"packagerHookInstalled": @(gPackagerHookInstalled),
+    @"packagerHookInstalled": @NO,
     @"bundleRootHookInstalled": @(gBundleRootHookInstalled),
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-debug-toolkit",
-  "version": "3.3.3",
+  "version": "3.3.4",
   "description": "A local-first React Native debug toolkit with Web Console, HTTP API, and MCP support for AI-readable app logs",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -11,6 +11,8 @@
     "bin",
     "node",
     "scripts",
+    "app.plugin.js",
+    "dev-client.js",
     "ios",
     "android",
     "react-native-debug-toolkit.podspec",
@@ -95,6 +97,6 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.29.2",
-    "pbxproj": "^0.0.5"
+    "xcode": "^3.0.1"
   }
 }

package/scripts/bundle/android.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const BEGIN = '// react-native-debug-toolkit: begin debug bundle';
+const END = '// react-native-debug-toolkit: end debug bundle';
+const REL_SCRIPT = '../../node_modules/react-native-debug-toolkit/scripts/debug-bundle.gradle';
+const EXPECTED_TASK = 'createDebugToolkitDebugJsAndAssets';
+const GRADLE_TASKS_ARGS = [':app:tasks', '--all', '--no-daemon', '--console=plain'];
+
+function findGradleFile(cwd) {
+  const groovy = path.join(cwd, 'android/app/build.gradle');
+  const kotlin = path.join(cwd, 'android/app/build.gradle.kts');
+
+  if (fs.existsSync(kotlin)) {
+    return { file: kotlin, kind: 'kotlin' };
+  }
+
+  if (fs.existsSync(groovy)) {
+    return { file: groovy, kind: 'groovy' };
+  }
+
+  throw new Error('android/app/build.gradle(.kts) not found.');
+}
+
+function block(kind) {
+  const applyLine = kind === 'kotlin'
+    ? `apply(from = "${REL_SCRIPT}")`
+    : `apply from: "${REL_SCRIPT}"`;
+
+  return `${BEGIN}\n${applyLine}\n${END}`;
+}
+
+function removeBlock(content) {
+  return content.replace(
+    /\/\/ react-native-debug-toolkit: begin debug bundle\n[\s\S]*?\/\/ react-native-debug-toolkit: end debug bundle\n?/g,
+    '',
+  );
+}
+
+function setupAndroidBundle(options) {
+  const gradle = findGradleFile(options.cwd);
+  const content = fs.readFileSync(gradle.file, 'utf8');
+
+  if (content.includes(BEGIN)) {
+    return { ok: true, changed: false, file: gradle.file };
+  }
+
+  fs.writeFileSync(gradle.file, `${content.trimEnd()}\n\n${block(gradle.kind)}\n`);
+  return { ok: true, changed: true, file: gradle.file };
+}
+
+function undoAndroidBundle(options) {
+  const gradle = findGradleFile(options.cwd);
+  const content = fs.readFileSync(gradle.file, 'utf8');
+  const next = removeBlock(content).replace(/\n{3,}/g, '\n\n');
+
+  if (next === content) {
+    return { ok: true, changed: false, file: gradle.file };
+  }
+
+  fs.writeFileSync(gradle.file, next);
+  return { ok: true, changed: true, file: gradle.file };
+}
+
+function checkAndroidBundle(options) {
+  const gradle = findGradleFile(options.cwd);
+  const content = fs.readFileSync(gradle.file, 'utf8');
+  const hasMarker = content.includes(BEGIN) && content.includes('scripts/debug-bundle.gradle');
+
+  if (!hasMarker) {
+    return { ok: false, reason: 'marker_missing', file: gradle.file };
+  }
+
+  const androidDir = path.join(options.cwd, 'android');
+  const gradlew = path.join(androidDir, 'gradlew');
+  const command = fs.existsSync(gradlew) ? gradlew : 'gradle';
+  const runGradle = options.runGradle || ((cmd, args, opts) => execFileSync(cmd, args, {
+    cwd: opts.cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }));
+  const output = runGradle(command, GRADLE_TASKS_ARGS, { cwd: androidDir });
+
+  if (!String(output).includes(EXPECTED_TASK)) {
+    return { ok: false, reason: 'gradle_task_missing', file: gradle.file };
+  }
+
+  return { ok: true, file: gradle.file };
+}
+
+module.exports = {
+  setupAndroidBundle,
+  undoAndroidBundle,
+  checkAndroidBundle,
+  BEGIN,
+  END,
+  EXPECTED_TASK,
+};

package/scripts/bundle/cli.js

@@ -0,0 +1,57 @@
+'use strict';
+
+function readOption(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function hasFlag(args, name) {
+  return args.includes(name);
+}
+
+function parseCommon(args, cwd) {
+  return {
+    cwd,
+    platform: readOption(args, '--platform') || 'all',
+    undo: hasFlag(args, '--undo'),
+    check: hasFlag(args, '--check'),
+    iosTarget: readOption(args, '--ios-target'),
+    yes: hasFlag(args, '--yes'),
+  };
+}
+
+async function runBundleCli(args, deps = {}) {
+  const cwd = deps.cwd || process.cwd();
+  const io = deps.io || {
+    writeOut: (value) => process.stdout.write(value),
+    writeErr: (value) => process.stderr.write(value),
+  };
+  const command = args[0];
+
+  if (command === 'setup-bundle') {
+    const setupBundle = deps.setupBundle || require('./setup').setupBundle;
+    await setupBundle(parseCommon(args.slice(1), cwd));
+    return 0;
+  }
+
+  if (command === 'doctor-bundle') {
+    const doctorBundle = deps.doctorBundle || require('./doctor').doctorBundle;
+    await doctorBundle({
+      cwd,
+      platform: readOption(args.slice(1), '--platform') || 'all',
+      app: readOption(args.slice(1), '--app'),
+      apk: readOption(args.slice(1), '--apk'),
+    });
+    return 0;
+  }
+
+  if (command === 'embed') {
+    io.writeErr('Unknown command: embed\nUse: debug-toolkit setup-bundle\n');
+    return 1;
+  }
+
+  io.writeErr(`Unknown command: ${command || '(none)'}\n`);
+  return 1;
+}
+
+module.exports = { runBundleCli };

package/scripts/bundle/doctor.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function readZipEntriesWithUnzip(file) {
+  const output = execFileSync('unzip', ['-Z1', file], { encoding: 'utf8' });
+  return output.split(/\r?\n/).filter(Boolean);
+}
+
+async function doctorIos(options) {
+  if (!options.app) throw new Error('--app is required for iOS doctor.');
+  const bundle = path.join(options.app, 'main.jsbundle');
+  if (!fs.existsSync(bundle)) {
+    throw new Error(`main.jsbundle not found in ${options.app}`);
+  }
+  return { ok: true, platform: 'ios', bundle };
+}
+
+async function doctorAndroid(options) {
+  if (!options.apk) throw new Error('--apk is required for Android doctor.');
+  const readZipEntries = options.readZipEntries || readZipEntriesWithUnzip;
+  const entries = await readZipEntries(options.apk);
+  const bundle = entries.find((entry) => /^assets\/.+\.bundle$/.test(entry));
+  if (!bundle) {
+    throw new Error(`Android JS bundle not found in ${options.apk}`);
+  }
+  return { ok: true, platform: 'android', bundle };
+}
+
+async function doctorBundle(options) {
+  if (options.platform === 'ios') return doctorIos(options);
+  if (options.platform === 'android') return doctorAndroid(options);
+  throw new Error(`Unsupported platform for doctor-bundle: ${options.platform}`);
+}
+
+module.exports = { doctorBundle, readZipEntriesWithUnzip };