xcobra 0.0.5 → 0.0.7

package/README.md

@@ -12,6 +12,7 @@ A toolkit for **iOS simulator automation** and development. Build apps, capture
 - **Heap Analysis**: Chrome DevTools-like heap snapshots
 - **Log Streaming**: Real-time simulator logs with app filtering
 - **Crash Reports**: Parse and display iOS crash reports with symbolicated backtraces
+- **Expo/React Native Debugging**: CDP-based debugging for Expo and React Native apps
 - **Zero Config**: Works as a drop-in replacement for xcodebuild
 
 ## Prerequisites
@@ -93,7 +94,7 @@ npx xcobra sim record-video --output recording.mp4 --codec hevc
 
 ### View Hierarchy (LLDB)
 
-#### `sim hierarchy` — Get UIKit View Hierarchy
+#### `sim hierarchy` (or `sim xml`) — Get UIKit View Hierarchy
 
 Get the full UIKit view hierarchy via LLDB, similar to Xcode's view debugger:
 
@@ -220,6 +221,100 @@ The formatted output includes:
 
 ---
 
+## Expo Commands (`expo`)
+
+Debug Expo and React Native apps via Chrome DevTools Protocol (CDP). All commands connect to the Metro dev server (default port 8081).
+
+### Quick Start
+
+```sh
+# List connected apps
+npx xcobra expo list
+
+# Evaluate JavaScript in the app
+npx xcobra expo eval "1 + 1"
+npx xcobra expo eval "expo.modules.FileSystem"
+
+# Stream console output
+npx xcobra expo console
+
+# Monitor network requests
+npx xcobra expo network
+```
+
+### `expo eval` — Evaluate JavaScript
+
+Evaluate JavaScript expressions in the running app. Objects are automatically inspected, and promises are awaited:
+
+```sh
+# Simple expressions
+npx xcobra expo eval "1 + 1"                    # => 2
+npx xcobra expo eval "Object.keys(global)"      # => ["__DEV__", ...]
+
+# Inspect objects (shows all properties including functions)
+npx xcobra expo eval "expo.modules.FileSystem"
+
+# Async functions work automatically
+npx xcobra expo eval "expo.modules.FileSystem.info(expo.modules.FileSystem.documentDirectory)"
+```
+
+### `expo network` — Monitor Network Requests
+
+Monitor HTTP requests from the app in real-time:
+
+```sh
+# Monitor all network traffic
+npx xcobra expo network
+
+# Monitor and trigger a request in the same connection
+npx xcobra expo network --eval "fetch('https://httpbin.org/get').then(r => r.json())"
+```
+
+The `--eval` flag is useful because CDP only allows one debugger connection per target. Using `--eval` triggers the request from the same connection that's monitoring.
+
+### `expo proxy` — Connection Sharing
+
+Start a CDP proxy to share connections between multiple commands:
+
+```sh
+# Start the proxy (runs in foreground)
+npx xcobra expo proxy
+
+# Now other commands share the connection
+npx xcobra expo eval "1 + 1"    # Uses proxy
+npx xcobra expo network         # Uses proxy, won't disconnect eval
+npx xcobra expo console         # Uses proxy
+```
+
+**Multiple Projects**: Each Metro port gets its own proxy, so you can run xcobra in multiple projects simultaneously:
+
+```sh
+# Terminal 1 - Project A on port 8081
+npx xcobra expo proxy &
+npx xcobra expo eval "1 + 1"
+
+# Terminal 2 - Project B on port 8082
+npx xcobra expo proxy --port 8082 &
+npx xcobra expo eval "2 + 2" --port 8082
+```
+
+### Source Inspection
+
+Inspect the JavaScript bundle loaded in the app:
+
+```sh
+# List all loaded scripts
+npx xcobra expo src scripts
+
+# Get source code of a specific script
+npx xcobra expo src source 42
+
+# List Metro modules
+npx xcobra expo src modules
+```
+
+---
+
 ## Build Commands
 
 Standard xcodebuild commands with pretty-formatted output:
@@ -256,6 +351,7 @@ Build logs are automatically saved to `.xcodebuild/xcodebuild.log`.
 | `sim screenshot` | Capture screenshot                    |
 | `sim record-video` | Record video                        |
 | `sim hierarchy`  | Get UIKit view hierarchy via LLDB     |
+| `sim xml`        | Alias for `sim hierarchy`             |
 | `sim heap`       | Heap memory analysis                  |
 | `sim keyboard`   | Toggle software keyboard              |
 | `sim log`        | Stream simulator logs                 |
@@ -270,6 +366,21 @@ Build logs are automatically saved to `.xcodebuild/xcodebuild.log`.
 | `crash <path>`      | Display specific crash report |
 | `crash --json`      | Output crash data as JSON     |
 
+### Expo Commands
+
+| Command              | Description                                |
+| -------------------- | ------------------------------------------ |
+| `expo list`          | List debuggable targets                    |
+| `expo eval <expr>`   | Evaluate JavaScript in the app             |
+| `expo console`       | Stream console output                      |
+| `expo network`       | Monitor network requests                   |
+| `expo proxy`         | Start CDP proxy for connection sharing     |
+| `expo reload`        | Reload the app                             |
+| `expo open-debugger` | Launch React Native DevTools               |
+| `expo src scripts`   | List loaded scripts                        |
+| `expo src source`    | Get script source code                     |
+| `expo src modules`   | List Metro modules                         |
+
 ---
 
 ## Development