argent-react-native-app-workflow

Physical iPhone (`kind: "device"`): Metro debugging and profiling tools reject it. Use a simulator. ## 1. Starting the React Native App ### 1.1 Explore Configuration (MANDATORY — Do This First) **Before running commands**, read the project's build and run configuration from the `argent-environment-inspector` subagent result. Do NOT default to `npx react-native start` or `npx react-native run-ios` without first checking for custom scripts and workflows. **Manual fallback** (if neither the agent nor the tool is available): read ALL `package.json` scripts — look for custom scripts like `start:local`, `start:dev`, `ios`, `build:ios`, flavors, etc. Custom scripts take priority over default commands. Also check `metro.config.js` for non-default port or watchFolders. For iOS builds, prefer opening `.xcworkspace` over `.xcodeproj` (CocoaPods generates the workspace). **If the project structure is convoluted, ask the user before proceeding.** **Remember the workflow:** Once you discover the project's build/run workflow, save it to project memory so you don't need to re-discover it each time. **Checklist before start:** - [ ] `node_modules` present (if not: `npm install` or `yarn`) - [ ] For iOS: `ios/Podfile` exists; if `ios/Pods` missing or stale, run `cd ios && pod install && cd ..` - [ ] No conflicting Metro on default port (see 1.2) ### 1.2 Start Metro 1. Check whether metro is already running on port found in configuration and if it is - do not start another server. Refer to point 2.1. 1. **Use the project's custom start script if one exists** (e.g. `npm run start:local`, `yarn start:dev`). Fall back to default commands if no custom scripts are defined: ```bash npx react-native start ``` Optional: `npx react-native start --reset-cache` if cache issues are suspected. 1. **Verify Metro is ready**: use the `debugger-status` tool. It returns a `status` result instead of erroring: `status: "connected"` or `status: "not_connected"` with `reason: "no_app_connected"` both mean Metro is up (the app just hasn't attached yet); `reason: "metro_not_running"` means Metro is not reachable — follow the result's `guidance`. 1. **Projects with flavors or custom configs**: Use project-specific start script if present (e.g. `npm run start:local`), and start Metro **before** running the app. ### 1.3 Run the App In a **separate** terminal (Metro keeps running in the first): **Use the project's custom build/run script if one exists** (e.g. `npm run ios`, `npm run android`, `yarn ios:debug`). Only fall back to the defaults below if no custom scripts are defined. **Pass the target device explicitly** — derive it from `list-devices` (see `<device_selection_rule>`): ```bash npx react-native run-ios --simulator="<name>" # iOS (or --udid <UDID>) npx react-native run-android --deviceId=<adb-serial> # Android ``` **Android only**: after install, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the emulator/device can reach Metro on your host. Repeat if the device restarts or adb drops. **Agent checklist:** - [ ] Metro is already running and shows "ready" - [ ] Command run from project root - [ ] If the device isn't booted yet: use `boot-device` with the iOS `udid` or Android `avdName`. Refer to the `argent-ios-simulator-setup` / `argent-android-emulator-setup` skill. - [ ] Android: `adb -s <serial> reverse tcp:8081 tcp:8081` done. --- ## 2. Ensuring / Debugging Metro ### 2.1 Check for Existing Metro Before starting Metro, avoid "port already in use" errors. Default port to check is :8081, infer the port from documentation: ```bash lsof -i :PORT ``` - **No output** → Port free; safe to start Metro. - **Output with PID** → Another process is using the port. Use the `debugger-status` tool to check whether the process on that port is actually a Metro server — it returns a structured result, not an error. `status: "connected"` or `reason: "no_app_connected"` → the process is Metro. `reason: "metro_not_running"` while `lsof` shows a listener → the port is occupied by something that is **not** Metro; the result's `detail` field shows what the process answered (`Metro at port ... is not running (got: ...)`). In that case ask the user whether you may kill the process. To kill a Metro process, use the `stop-metro` tool (requires user confirmation). ### 2.2 Confirm Correct Server Connection - **App must point at the same host/port as the running Metro.** Default: same machine, port 8081. - **iOS Simulator:** By default uses localhost; no extra config needed for same-machine Metro. **Verify Metro is reachable:** use the `debugger-status` tool. `reason: "metro_not_running"` means Metro did not answer on that port — start it (§2.1); `"no_app_connected"` means Metro answered but the app has not attached (§2.3). Any other reason: follow the result's `guidance` (it does not by itself prove Metro is up). ### 2.3 Reload the App (Ensure New Bundle) After code or config changes, the app must load the new bundle: | Method | How | | ----------- | ------------------------------------------------------------------------------------------------- | | Reload tool | Use the `debugger-reload-metro` tool | | Restart app | Use the `restart-app` tool, or kill the app in simulator and run `npx react-native run-ios` again | **Agent checklist:** - [ ] Only one Metro process (no duplicate on port) - [ ] App was started after Metro was ready - [ ] When needing to reload: refer to 2.3 --- ## 3. Build / Install / Retry (React Native & iOS Native) ### 3.1 When Build Fails (e.g. xcodebuild exit code 65) **Order of operations (simplest first):** 1. Clean build folder, then retry the build command 2. Clear caches and reinstall dependencies: reset Metro cache, `watchman watch-del-all`, remove `node_modules` + lockfile, `npm install`, then `cd ios && rm -rf build Pods Podfile.lock && pod install --repo-update` 3. CocoaPods issues: `pod deintegrate` then `pod install --repo-update` 4. Open `ios/*.xcworkspace` in Xcode for detailed errors in the Report navigator ### 3.2 When to Ask the User **After 2-3 failed build or run attempts, STOP and ask the user for guidance.** The user may know about required env vars, Xcode version requirements, custom build configurations, monorepo-specific setup, or required external services. If the project structure is convoluted and the correct build approach is not obvious, **ask the user early** rather than guessing. ### 3.3 Saving Build Workflow for Later Once you discover the correct build/run workflow for a project, **save it to project memory**. Capture: commands to start Metro, commands to build/run the app, and any required environment setup. ### 3.4 When to Reinstall vs Refresh | Situation | Action | | ----------------------------------------------------- | ------------------------------------------------------------------------------------- | | JS/React only changed | Use `debugger-reload-metro` tool. No rebuild. | | Native code or `pod install` / project config changed | Rebuild: `npx react-native run-ios` (Metro can stay running). | | `node_modules` or `package.json` changed | `npm install`, then if native deps changed run `cd ios && pod install`. Then rebuild. | | App needs reinstalling from .app path | Use `reinstall-app` tool with UDID, bundle ID, and .app path. | | Persistent native build errors | Full clean + reinstall (step 2 above). | ### 3.5 Device Control | Action | Tool / Command | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | List devices | `list-devices` tool (iOS + Android) | | Boot an iOS simulator | `boot-device` tool with `udid` | | Boot an Android emulator | `boot-device` tool with `avdName` | | Launch an app | `launch-app` tool (pass device id + bundle id / package name) | | Restart an app | `restart-app` tool (pass device id + bundle id / package name) | | Open a URL / deep link | `open-url` tool (pass device id + URL) | | Rotate device | `rotate` tool | | Stop simulator server | `stop-simulator-server` tool (iOS UDID or Android serial — one device) | | Stop all simulator servers | `stop-all-simulator-servers` tool — pass `devices: [...]` to scope the teardown to this session's devices (an unscoped call also tears down other agents' devices; use it only for a machine-wide cleanup) | For full simulator setup workflow, refer to the `argent-ios-simulator-setup` skill. --- ## 4. Runtime Problems in the App ### 4.1 Where to Look | Problem type | Tool / Where to look | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **JavaScript errors / logs** | Use `debugger-log-registry` to get a summary and log file path, then `Grep` to search. If it returns `status: "not_connected"`, no log file is returned — follow its `guidance` to reconnect first. | | **React component hierarchy** | Use `debugger-component-tree` tool for a text tree, or `debugger-inspect-element` at specific logical pixel coordinates (not normalized 0-1). | | **Visual state of the app** | Use `screenshot` tool to capture the current screen, but prefer `describe` or `debugger-component-tree` for actual navigation and target discovery. If a permission prompt or system-owned modal overlay is not exposed reliably, then fall back to `screenshot`. | | **Evaluate JS in the app** | Use `debugger-evaluate` tool to run JavaScript in the app's runtime. | | **Native crashes / native stack** | `npx react-native log-ios` or iOS Simulator: Debug → Open System Log. | | **Build/runtime config** | `metro.config.js`, `babel.config.js`, `package.json` scripts, `ios/Podfile`. | For comprehensive Metro debugging workflows (component inspection, console logs, JS evaluation), refer to the `argent-metro-debugger` skill. ### 4.2 JS Console Logs (Log Registry) Logs are written to a flat log file on disk under `~/.argent/tmp/`. Use the **log-registry → grep** pattern instead of reading logs inline.