diff --git a/.agents/skills/repack-debug-runtime/SKILL.md b/.agents/skills/repack-debug-runtime/SKILL.md new file mode 100644 index 000000000..4a84e0ffa --- /dev/null +++ b/.agents/skills/repack-debug-runtime/SKILL.md @@ -0,0 +1,221 @@ +--- +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 | +| --- | --- | +| `