From cd3d309a3ee6c1f32446155981e1e8556ac12cbf Mon Sep 17 00:00:00 2001 From: Daniel Williams Date: Thu, 22 Oct 2026 14:18:59 +0100 Subject: [PATCH 1/4] feat: add Re.Pack DevTools plugin with agent tools for runtime debugging Add a private, workspace-only Rozenite plugin (packages/repack-devtools-plugin) that records ScriptManager activity, Module Federation runtime state and events, uncaught errors, dev-server compilations and requests, and turns them into diagnostics. - Panels for scripts, federation, dev server and errors/symbolication - 16 `rozenite agent callstack/repack-devtools` tools, including actions to reproduce issues headlessly (load-script, load-remote, invalidate-scripts, symbolicate, reload) - `withRepackDevTools` adds a compilation collector and `/repack-devtools/state` endpoints to any Re.Pack dev server - MF 2 runtime plugin export for recording from container start-up Wire it into all tester apps behind WITH_ROZENITE=true and add the repack-debug-runtime and repack-reproduce-issue skills describing how to use it to reproduce and root-cause issues. --- .agents/skills/repack-debug-runtime/SKILL.md | 173 ++++ .../skills/repack-reproduce-issue/SKILL.md | 89 ++ .claude/skills/repack-debug-runtime | 1 + .claude/skills/repack-reproduce-issue | 1 + .gitignore | 3 + CONTRIBUTING.md | 2 + agent_context/README.md | 1 + .../repack-devtools-oct2026/design.md | 86 ++ apps/tester-app/index.js | 2 + apps/tester-app/package.json | 2 + apps/tester-app/rspack.config.mjs | 12 +- apps/tester-app/src/App.tsx | 2 + apps/tester-app/webpack.config.mjs | 12 +- apps/tester-expo/app/_layout.tsx | 2 + apps/tester-expo/package.json | 2 + apps/tester-expo/rspack.config.mjs | 18 +- apps/tester-federation-v2/config.host-app.mts | 12 +- apps/tester-federation-v2/config.mini-app.mts | 9 +- .../configs/rspack.host-app.mts | 13 + apps/tester-federation-v2/package.json | 2 + apps/tester-federation-v2/src/host/App.tsx | 2 + apps/tester-federation-v2/src/host/index.js | 2 + apps/tester-federation/config.host-app.mts | 12 +- apps/tester-federation/config.mini-app.mts | 9 +- apps/tester-federation/package.json | 2 + apps/tester-federation/src/host/App.tsx | 2 + apps/tester-federation/src/host/index.js | 2 + packages/repack-devtools-plugin/README.md | 54 + packages/repack-devtools-plugin/bundler.ts | 8 + packages/repack-devtools-plugin/package.json | 75 ++ .../repack-devtools-plugin/react-native.ts | 24 + .../repack-devtools-plugin/rozenite.config.ts | 9 + .../scripts/rozenite.mjs | 53 + packages/repack-devtools-plugin/sdk.ts | 22 + .../src/__tests__/bundler.test.ts | 258 +++++ .../src/__tests__/federationState.test.ts | 192 ++++ .../__tests__/scriptManagerRecorder.test.ts | 131 +++ .../src/__tests__/symbolication.test.ts | 170 +++ .../src/bundler/collector.ts | 148 +++ .../src/bundler/diagnostics.ts | 131 +++ .../src/bundler/middleware.ts | 185 ++++ .../src/bundler/store.ts | 64 ++ .../src/bundler/withRepackDevTools.ts | 89 ++ .../src/react-native/api.ts | 367 +++++++ .../src/react-native/environment.ts | 93 ++ .../src/react-native/errorRecorder.ts | 39 + .../react-native/federation/runtimePlugin.ts | 264 +++++ .../src/react-native/federation/state.ts | 316 ++++++ .../src/react-native/install.ts | 78 ++ .../src/react-native/rows.ts | 68 ++ .../src/react-native/scriptManagerRecorder.ts | 302 ++++++ .../src/react-native/store.ts | 155 +++ .../src/react-native/symbolication.ts | 265 +++++ .../src/react-native/useRepackDevTools.ts | 88 ++ .../useRepackDevToolsAgentTools.ts | 203 ++++ .../src/shared/agent-tools.ts | 493 +++++++++ .../src/shared/constants.ts | 21 + .../src/shared/guards.ts | 78 ++ .../src/shared/messaging.ts | 51 + .../src/shared/types.ts | 313 ++++++ .../src/ui/components.tsx | 125 +++ .../repack-devtools-plugin/src/ui/css.d.ts | 2 + .../src/ui/dev-server-panel.tsx | 194 ++++ .../src/ui/errors-panel.tsx | 207 ++++ .../src/ui/federation-panel.tsx | 281 +++++ .../src/ui/scripts-panel.tsx | 229 ++++ .../src/ui/useDevToolsData.ts | 93 ++ .../tsconfig.bundler.json | 16 + packages/repack-devtools-plugin/tsconfig.json | 34 + .../repack-devtools-plugin/vite.config.ts | 15 + .../repack-devtools-plugin/vitest.config.ts | 8 + pnpm-lock.yaml | 974 ++++++++++++++++-- pnpm-workspace.yaml | 1 + 73 files changed, 7339 insertions(+), 122 deletions(-) create mode 100644 .agents/skills/repack-debug-runtime/SKILL.md create mode 100644 .agents/skills/repack-reproduce-issue/SKILL.md create mode 120000 .claude/skills/repack-debug-runtime create mode 120000 .claude/skills/repack-reproduce-issue create mode 100644 agent_context/repack-devtools-oct2026/design.md create mode 100644 packages/repack-devtools-plugin/README.md create mode 100644 packages/repack-devtools-plugin/bundler.ts create mode 100644 packages/repack-devtools-plugin/package.json create mode 100644 packages/repack-devtools-plugin/react-native.ts create mode 100644 packages/repack-devtools-plugin/rozenite.config.ts create mode 100644 packages/repack-devtools-plugin/scripts/rozenite.mjs create mode 100644 packages/repack-devtools-plugin/sdk.ts create mode 100644 packages/repack-devtools-plugin/src/__tests__/bundler.test.ts create mode 100644 packages/repack-devtools-plugin/src/__tests__/federationState.test.ts create mode 100644 packages/repack-devtools-plugin/src/__tests__/scriptManagerRecorder.test.ts create mode 100644 packages/repack-devtools-plugin/src/__tests__/symbolication.test.ts create mode 100644 packages/repack-devtools-plugin/src/bundler/collector.ts create mode 100644 packages/repack-devtools-plugin/src/bundler/diagnostics.ts create mode 100644 packages/repack-devtools-plugin/src/bundler/middleware.ts create mode 100644 packages/repack-devtools-plugin/src/bundler/store.ts create mode 100644 packages/repack-devtools-plugin/src/bundler/withRepackDevTools.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/api.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/environment.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/errorRecorder.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/federation/runtimePlugin.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/federation/state.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/install.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/rows.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/scriptManagerRecorder.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/store.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/symbolication.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/useRepackDevTools.ts create mode 100644 packages/repack-devtools-plugin/src/react-native/useRepackDevToolsAgentTools.ts create mode 100644 packages/repack-devtools-plugin/src/shared/agent-tools.ts create mode 100644 packages/repack-devtools-plugin/src/shared/constants.ts create mode 100644 packages/repack-devtools-plugin/src/shared/guards.ts create mode 100644 packages/repack-devtools-plugin/src/shared/messaging.ts create mode 100644 packages/repack-devtools-plugin/src/shared/types.ts create mode 100644 packages/repack-devtools-plugin/src/ui/components.tsx create mode 100644 packages/repack-devtools-plugin/src/ui/css.d.ts create mode 100644 packages/repack-devtools-plugin/src/ui/dev-server-panel.tsx create mode 100644 packages/repack-devtools-plugin/src/ui/errors-panel.tsx create mode 100644 packages/repack-devtools-plugin/src/ui/federation-panel.tsx create mode 100644 packages/repack-devtools-plugin/src/ui/scripts-panel.tsx create mode 100644 packages/repack-devtools-plugin/src/ui/useDevToolsData.ts create mode 100644 packages/repack-devtools-plugin/tsconfig.bundler.json create mode 100644 packages/repack-devtools-plugin/tsconfig.json create mode 100644 packages/repack-devtools-plugin/vite.config.ts create mode 100644 packages/repack-devtools-plugin/vitest.config.ts diff --git a/.agents/skills/repack-debug-runtime/SKILL.md b/.agents/skills/repack-debug-runtime/SKILL.md new file mode 100644 index 000000000..9c0c80de6 --- /dev/null +++ b/.agents/skills/repack-debug-runtime/SKILL.md @@ -0,0 +1,173 @@ +--- +name: repack-debug-runtime +description: > + Use when inspecting a running Re.Pack app or dev server to find out why + something fails at runtime: chunks or scripts not loading (404, timeouts, + cache), Module Federation remotes/shared packages misbehaving, compilation or + HMR errors, LogBox stacks that are not symbolicated, or uncaught JS errors. + Covers starting the tester apps with the Re.Pack DevTools plugin, the + `rozenite agent` tools of `callstack/repack-devtools`, the + `/repack-devtools/*` dev-server endpoints, and playbooks per failure type. +--- + +# Debug a running Re.Pack app + +`packages/repack-devtools-plugin` (private, workspace only) records what +Re.Pack does at runtime and on the dev server, computes diagnostics, and +exposes them two ways: + +- **App side** (needs a running app): `rozenite agent callstack/repack-devtools ` +- **Dev-server side** (works without an app, even when the bundle fails to + build): `curl /repack-devtools/state` + +Both are wired into every tester app behind `WITH_ROZENITE=true`. Never touch +ports or devices you did not start: other sessions often own `8081` and +`emulator-5554`. + +## 1. Start + +```sh +cd apps/tester-app # or tester-federation, tester-federation-v2, tester-expo +WITH_ROZENITE=true pnpm start --port 8091 # MF testers: start:hostapp / start:miniapp +``` + +The log must show `[Rozenite] Loaded N plugin(s)` including +`@callstack/repack-devtools-plugin`. Check the endpoint before launching the app: + +```sh +curl -s localhost:8091/repack-devtools/state?requests=none +``` + +Point a debug build at the port (Android; package ids are in each `app.json`): + +```sh +adb -s reverse tcp:8091 tcp:8091 +adb -s shell "run-as sh -c 'mkdir -p shared_prefs && echo \"localhost:8091\" > shared_prefs/_preferences.xml'" +adb -s shell am force-stop +adb -s shell am start -n /com.microsoft.reacttestapp.MainActivity +``` + +MF remotes have fixed URLs in the host config (`localhost:8082`, `8083`); also +`adb reverse` those ports. On iOS simulators, `localhost` already reaches the +host; use the dev menu or `RCT_jsLocation` to change the port. + +## 2. Inspect + +Run from an app directory so `rozenite` resolves (`pnpm exec rozenite …`). +Pass `--port ` to every call. + +```sh +pnpm exec rozenite agent targets --port 8091 # app connected? +pnpm exec rozenite agent callstack/repack-devtools get-overview --port 8091 +pnpm exec rozenite agent session stop --port 8091 # when done +``` + +**Always start with `get-overview`.** It returns app info (platform, RN +version, bundle URL, public path, dev server), record counts, and +severity-sorted `diagnostics` merged from the app and the dev server. Every +diagnostic has a `ref` that tells you which tool gives details: + +| `ref` | Follow up with | +| --- | --- | +| `