xcobra 0.0.2 → 0.0.4

package/README.md

@@ -1,19 +1,18 @@
 # $ bunx xcobra
 
-A full toolkit for **headless iOS agent development** and automation. Build apps, interact with simulators, capture screens, and control UI—all from the command line.
+A toolkit for **iOS simulator automation** and development. Build apps, capture screens, record video, and debug via LLDB—all from the command line.
 
 <img width="1530" height="738" alt="xcobra" src="https://github.com/user-attachments/assets/802373aa-2e5e-4c68-8c61-3b751c9b44b2" />
 
 ## Features
 
-- 🤖 **Headless Agent Toolkit**: Complete set of commands for building AI agents that interact with iOS simulators
-- ✨ **Pretty Build Output**: Clean, colored formatting for xcodebuild operations
-- 📱 **Simulator Control**: Tap, swipe, type, press buttons, and more
-- 📸 **Screen Capture**: Screenshots and video recording
-- 🌳 **Accessibility Tree**: Query UI elements as XML for element targeting
-- 📝 **Log Streaming**: Real-time simulator logs with app filtering
-- 💥 **Crash Reports**: Parse and display iOS crash reports with symbolicated backtraces
-- 🚀 **Zero Config**: Works as a drop-in replacement for xcodebuild
+- **Pretty Build Output**: Clean, colored formatting for xcodebuild operations
+- **Screen Capture**: Screenshots and video recording via simctl
+- **View Hierarchy**: Get UIKit view hierarchy via LLDB debugging
+- **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
+- **Zero Config**: Works as a drop-in replacement for xcodebuild
 
 ## Prerequisites
 
@@ -23,17 +22,6 @@ A full toolkit for **headless iOS agent development** and automation. Build apps
 xcode-select --install
 ```
 
-### AXe (Apple Accessibility CLI)
-
-This toolkit requires [AXe](https://github.com/cameroncooke/AXe) for simulator interaction commands. Install via Homebrew:
-
-```sh
-brew tap cameroncooke/axe
-brew install axe
-```
-
-AXe provides low-level access to iOS Simulator accessibility APIs, enabling touch simulation, keyboard input, hardware button presses, and screen capture.
-
 ## Installation
 
 ```sh
@@ -44,58 +32,20 @@ npx xcobra <args>
 npm install -g xcobra
 ```
 
-## Quick Start for Agent Development
+## Quick Start
 
 ```sh
-# 1. Build your app
-npx xcobra -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' build
-
-# 2. Get the accessibility tree (for element targeting)
-npx xcobra sim xml
-
-# 3. Tap on an element by label
-npx xcobra sim tap --label "Sign In"
-
-# 4. Type text
-npx xcobra sim type "hello@example.com"
+# Build your app
+npx xcobra build -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16'
 
-# 5. Take a screenshot
+# Take a screenshot
 npx xcobra sim screenshot --output ./screenshot.png
-```
-
-### Example: Finding and Tapping a Button
-
-First, get the accessibility tree to discover elements:
-
-```sh
-npx xcobra sim xml
-```
-
-This outputs XML like:
-
-```xml
-<AXApplication label="MyApp" enabled="true">
-  <AXWindow>
-    <AXScrollView>
-      <AXButton label="Sign In" enabled="true" x="147" y="680" width="120" height="44" />
-      <AXTextField label="Email" value="" x="40" y="320" width="334" height="44" />
-      <AXSecureTextField label="Password" value="" x="40" y="380" width="334" height="44" />
-    </AXScrollView>
-  </AXWindow>
-</AXApplication>
-```
 
-Then tap the button using any of these methods:
+# Record video
+npx xcobra sim record-video --output ./recording.mp4
 
-```sh
-# By label (recommended for readability)
-npx xcobra sim tap --label "Sign In"
-
-# By coordinates (from x/y attributes)
-npx xcobra sim tap --x 207 --y 702
-
-# By accessibility identifier (if set in code)
-npx xcobra sim tap --id "signInButton"
+# Get view hierarchy (auto-detects running app)
+npx xcobra sim hierarchy
 ```
 
 ---
@@ -104,16 +54,7 @@ npx xcobra sim tap --id "signInButton"
 
 All simulator commands automatically detect the booted simulator. Use `--udid <UDID>` to target a specific device.
 
-### Accessibility & UI Inspection
-
-#### `sim xml` — Get Accessibility Tree
-
-Output the full accessibility tree as XML for UI element discovery and targeting:
-
-```sh
-npx xcobra sim xml
-npx xcobra sim xml --udid <SIMULATOR_UDID>
-```
+### Device Listing
 
 #### `sim list` — List Simulators
 
@@ -121,154 +62,100 @@ Display all available iOS simulators:
 
 ```sh
 npx xcobra sim list
+npx xcobra sim list --json
 ```
 
-### Touch & Gestures
+### Screenshots & Video
 
-#### `sim tap` — Tap on Screen
+#### `sim screenshot` — Capture Screenshot
 
-Tap at coordinates or on accessibility elements:
+Capture the simulator display as PNG:
 
 ```sh
-# Tap at coordinates
-npx xcobra sim tap --x 100 --y 200
-
-# Tap element by accessibility identifier
-npx xcobra sim tap --id "loginButton"
-
-# Tap element by label
-npx xcobra sim tap --label "Sign In"
+# Auto-generated filename
+npx xcobra sim screenshot
 
-# With delays (seconds)
-npx xcobra sim tap --x 100 --y 200 --pre-delay 1.0 --post-delay 0.5
+# Custom output path
+npx xcobra sim screenshot --output ~/Desktop/screenshot.png
 ```
 
-#### `sim swipe` — Swipe Gesture
+#### `sim record-video` — Record Video
 
-Execute swipe gestures with configurable start/end points:
+Record simulator video:
 
 ```sh
-# Basic swipe
-npx xcobra sim swipe --start-x 100 --start-y 500 --end-x 100 --end-y 200
+# Basic recording (press Ctrl+C to stop)
+npx xcobra sim record-video --output recording.mp4
 
-# Slow swipe with custom duration
-npx xcobra sim swipe --start-x 50 --start-y 500 --end-x 350 --end-y 500 --duration 2.0
+# With codec option
+npx xcobra sim record-video --output recording.mp4 --codec hevc
 ```
 
-#### `sim touch` — Low-level Touch Control
-
-Fine-grained touch down/up events for complex gestures:
-
-```sh
-# Touch down
-npx xcobra sim touch --x 150 --y 250 --down
-
-# Touch up
-npx xcobra sim touch --x 150 --y 250 --up
-
-# Touch down, wait, then up
-npx xcobra sim touch --x 150 --y 250 --down --up --delay 1.0
-```
+### View Hierarchy (LLDB)
 
-#### `sim gesture` — Preset Gestures
+#### `sim hierarchy` — Get UIKit View Hierarchy
 
-Common gesture patterns:
+Get the full UIKit view hierarchy via LLDB, similar to Xcode's view debugger:
 
 ```sh
-npx xcobra sim gesture scroll-up
-npx xcobra sim gesture scroll-down
-npx xcobra sim gesture scroll-left
-npx xcobra sim gesture scroll-right
-npx xcobra sim gesture swipe-from-left-edge
-npx xcobra sim gesture swipe-from-right-edge
-npx xcobra sim gesture swipe-from-top-edge
-npx xcobra sim gesture swipe-from-bottom-edge
-
-# With delays
-npx xcobra sim gesture scroll-down --pre-delay 1.0 --post-delay 0.5
-```
-
-### Text Input
-
-#### `sim type` — Type Text
-
-Input text with automatic keyboard handling:
+# Get view hierarchy (auto-detects running app)
+npx xcobra sim hierarchy
 
-```sh
-# Direct text input
-npx xcobra sim type "Hello World!"
+# Get view controller hierarchy
+npx xcobra sim hierarchy --controllers
 
-# From stdin
-echo "Complex text" | npx xcobra sim type --stdin
+# Get Auto Layout constraint trace
+npx xcobra sim hierarchy --constraints
 
-# From file
-npx xcobra sim type --file input.txt
+# Or target a specific app
+npx xcobra sim hierarchy --bundle-id com.example.myapp
 ```
 
-### Hardware Buttons
+**Note**: The hierarchy command attaches LLDB to the running app, which briefly pauses execution. Only works with debuggable apps (not system apps).
 
-#### `sim button` — Press Hardware Buttons
+### Heap Memory Analysis
 
-Simulate hardware button presses:
+#### `sim heap` — Chrome DevTools-like Heap Snapshots
 
-```sh
-npx xcobra sim button home
-npx xcobra sim button lock
-npx xcobra sim button side-button
-npx xcobra sim button siri
-npx xcobra sim button apple-pay
-
-# Long press
-npx xcobra sim button lock --duration 2.0
-```
+Analyze heap memory using LLDB:
 
-### Keyboard Control
+```sh
+# Get heap summary (auto-detects running app)
+npx xcobra sim heap summary
 
-#### `sim key` — Press Individual Key
+# Take a full heap snapshot
+npx xcobra sim heap snapshot --output snapshot.json
 
-Press keys by HID keycode:
+# Inspect a specific object by address
+npx xcobra sim heap inspect 0x7f8b12345678
 
-```sh
-npx xcobra sim key 40          # Enter key
-npx xcobra sim key 42 --duration 1.0  # Long press
+# Or target a specific app
+npx xcobra sim heap summary --bundle-id com.example.myapp
 ```
 
-#### `sim key-sequence` — Press Key Sequence
+### Keyboard
 
-Execute multiple keycodes in sequence:
+#### `sim keyboard` — Toggle Software Keyboard
 
 ```sh
-npx xcobra sim key-sequence --keycodes 11,8,15,15,18  # Types "hello"
+npx xcobra sim keyboard
 ```
 
-### Screenshots & Video
+### Logging
 
-#### `sim screenshot` — Capture Screenshot
+#### `sim log` — Stream Logs
 
-Capture the simulator display as PNG:
+Stream logs from the simulator:
 
 ```sh
-# Auto-generated filename
-npx xcobra sim screenshot
-
-# Custom output path
-npx xcobra sim screenshot --output ~/Desktop/screenshot.png
-
-# Output to directory (auto-generates filename)
-npx xcobra sim screenshot --output ~/Desktop/
-```
-
-#### `sim record-video` — Record Video
-
-Record simulator video to MP4:
+# All logs from booted simulator
+npx xcobra sim log
 
-```sh
-# Basic recording (press Ctrl+C to stop)
-npx xcobra sim record-video --output recording.mp4
+# Filter by app bundle identifier
+npx xcobra sim log --app-id com.example.myapp
 
-# With options
-npx xcobra sim record-video --output recording.mp4 --fps 30
-npx xcobra sim record-video --output low-bandwidth.mp4 --fps 10 --quality 60 --scale 0.5
+# Specific simulator
+npx xcobra sim log --udid <SIMULATOR_UDID>
 ```
 
 ### Appearance
@@ -283,26 +170,6 @@ xcrun simctl ui booted appearance dark
 
 # Set to light mode
 xcrun simctl ui booted appearance light
-
-# Target specific simulator
-xcrun simctl ui <UDID> appearance dark
-```
-
-### Logging
-
-#### `sim log` — Stream Logs
-
-Stream logs from the simulator:
-
-```sh
-# All logs from booted simulator
-npx xcobra sim log
-
-# Filter by app bundle identifier
-npx xcobra sim log --app-id com.example.myapp
-
-# Specific simulator
-npx xcobra sim log --udid <SIMULATOR_UDID>
 ```
 
 ---
@@ -329,22 +196,6 @@ npx xcobra crash list
 npx xcobra crash list --json
 ```
 
-Example output:
-
-```
-Found 5 crash report(s):
-
-  RouterE2E
-    Bundle ID: com.expo.routere2e
-    Date: 12/31/2025, 12:14:36 PM
-    Path: /Users/.../RouterE2E-2025-12-31-121436.ips
-
-  MyApp
-    Bundle ID: com.example.myapp
-    Date: 12/30/2025, 3:45:22 PM
-    Path: /Users/.../MyApp-2025-12-30-154522.ips
-```
-
 ### `crash <path>` — View Specific Crash
 
 Display a specific crash report file:
@@ -367,98 +218,6 @@ The formatted output includes:
 - **Other Threads**: Condensed backtraces showing top 5 frames
 - **Binary Images**: App-related dylibs with UUIDs for symbolication
 
-Example output:
-
-```
-────────────────────────────────────────────────────────────────────────────────
-CRASH REPORT: RouterE2E
-────────────────────────────────────────────────────────────────────────────────
-
-Process Information:
-  Process:         RouterE2E
-  Bundle ID:       com.expo.routere2e
-  Version:         0.0.0 (1)
-
-Exception Information:
-  Type:            EXC_BAD_ACCESS (SIGSEGV)
-  Subtype:         KERN_INVALID_ADDRESS at 0x0000000000000000
-
-────────────────────────────────────────────────────────────────────────────────
-CRASHED THREAD 0 (com.apple.main-thread)
-────────────────────────────────────────────────────────────────────────────────
-   0  RouterE2E.debug.dylib  0x0000000104c90b94  +[SentrySDKInternal crash] + 20 (SentrySDKInternal.m:701)
-   1  RouterE2E.debug.dylib  0x0000000104d67f6c  static SentrySDK.crash() + 44 (SentrySDK.swift:339)
-   2  RouterE2E.debug.dylib  0x0000000104b45b7c  +[SentrySDKWrapper crash] + 36 (SentrySDKWrapper.m:15)
-   3  RouterE2E.debug.dylib  0x0000000104b33104  -[RNSentry crash] + 36 (RNSentry.mm:713)
-   ...
-```
-
----
-
-## Agent Debugging Workflow
-
-When building AI agents that interact with iOS apps, crashes are inevitable. Here's how to use the crash commands to debug issues:
-
-### 1. Detect a Crash
-
-When your agent's action causes an unexpected app termination:
-
-```sh
-# Check if there's a recent crash
-npx xcobra crash list
-```
-
-### 2. Analyze the Crash
-
-View the crash details to understand what went wrong:
-
-```sh
-# View the latest crash
-npx xcobra crash
-
-# Or get JSON for programmatic analysis
-npx xcobra crash --json
-```
-
-### 3. Identify the Root Cause
-
-The crash report shows:
-
-- **Exception type**: `EXC_BAD_ACCESS` = memory issue, `EXC_CRASH` = uncaught exception
-- **Crashed thread backtrace**: Shows exactly where the crash occurred with source file:line
-- **Binary images**: Which frameworks/libraries were involved
-
-### 4. Example: Agent Workflow with Crash Detection
-
-```sh
-# Agent attempts an action
-npx xcobra sim tap --label "Submit"
-
-# Check if app is still responsive by getting UI tree
-npx xcobra sim xml
-
-# If the above fails or returns empty, check for crash
-npx xcobra crash --json | jq '.header.app_name, .body.exception.type'
-```
-
-### 5. Automated Crash Monitoring
-
-For continuous agent operation, monitor crashes programmatically:
-
-```sh
-# Get crash data as JSON for parsing
-CRASH_DATA=$(npx xcobra crash --json)
-
-# Extract key information
-echo "$CRASH_DATA" | jq '{
-  app: .header.app_name,
-  time: .body.captureTime,
-  exception: .body.exception.type,
-  signal: .body.exception.signal,
-  reason: .body.termination.indicator
-}'
-```
-
 ---
 
 ## Build Commands
@@ -467,11 +226,11 @@ Standard xcodebuild commands with pretty-formatted output:
 
 ```sh
 # Build a project
-npx xcobra -project MyApp.xcodeproj -scheme MyApp -configuration Debug build
+npx xcobra build -project MyApp.xcodeproj -scheme MyApp -configuration Debug
 
 # Build for simulator
-npx xcobra -project MyApp.xcodeproj -scheme MyApp \
-  -destination 'platform=iOS Simulator,name=iPhone 16' build
+npx xcobra build -project MyApp.xcodeproj -scheme MyApp \
+  -destination 'platform=iOS Simulator,name=iPhone 16'
 
 # Show version (raw output)
 npx xcobra -version
@@ -491,22 +250,15 @@ Build logs are automatically saved to `.xcodebuild/xcodebuild.log`.
 
 ### Simulator Commands
 
-| Command            | Description                           |
-| ------------------ | ------------------------------------- |
-| `sim xml`          | Get accessibility tree as XML         |
-| `sim list`         | List all simulators                   |
-| `sim tap`          | Tap at coordinates or on element      |
-| `sim swipe`        | Swipe gesture                         |
-| `sim touch`        | Low-level touch down/up               |
-| `sim gesture`      | Preset gestures (scroll, edge swipes) |
-| `sim type`         | Type text                             |
-| `sim button`       | Press hardware buttons                |
-| `sim key`          | Press individual key by keycode       |
-| `sim key-sequence` | Press sequence of keys                |
-| `sim screenshot`   | Capture screenshot                    |
-| `sim record-video` | Record video                          |
-| `sim log`          | Stream simulator logs                 |
-| `xcrun simctl ui`  | Toggle appearance (dark/light mode)   |
+| Command          | Description                           |
+| ---------------- | ------------------------------------- |
+| `sim list`       | List all simulators                   |
+| `sim screenshot` | Capture screenshot                    |
+| `sim record-video` | Record video                        |
+| `sim hierarchy`  | Get UIKit view hierarchy via LLDB     |
+| `sim heap`       | Heap memory analysis                  |
+| `sim keyboard`   | Toggle software keyboard              |
+| `sim log`        | Stream simulator logs                 |
 
 ### Crash Report Commands
 
@@ -517,7 +269,6 @@ Build logs are automatically saved to `.xcodebuild/xcodebuild.log`.
 | `crash list`        | List recent crash reports     |
 | `crash <path>`      | Display specific crash report |
 | `crash --json`      | Output crash data as JSON     |
-| `crash list --json` | Output crash list as JSON     |
 
 ---
 
@@ -531,7 +282,7 @@ bun install
 bun run build
 
 # Test locally
-./dist/index.js sim xml
+./dist/index.js sim list
 ```
 
 Claude Code + xcode, brah