Add reloaderoo context primer

Author: cameroncooke

docs/RELOADEROO_XCODEBUILDMCP_PRIMER.md

@@ -0,0 +1,332 @@
+# Reloaderoo + XcodeBuildMCP: Curated CLI Primer
+
+Use this primer to drive XcodeBuildMCP entirely through Reloaderoo—treating it like a CLI. It is designed to be included in your agent’s context to show exactly how to invoke the specific tools your project needs.
+
+Why this file:
+- XcodeBuildMCP exposes many tools. Dumping the full tool surface into the context wastes tokens.
+- Instead, copy this file into your project and delete everything you don’t need. Keep only the commands relevant to your workflow (e.g., just Simulator tools).
+- Your trimmed version becomes a small, project‑specific reference that tells your agent precisely which Reloaderoo tool calls to make.
+
+How to use this primer:
+1. Copy this file into your repo (e.g., docs/xcodebuildmcp_primer.md or AGENTS.md).
+2. Remove all sections and commands you don’t use. Keep it minimal.
+3. Replace placeholders with your real values (paths, schemes, simulator UUIDs/Names, bundle IDs, etc.).
+4. Use the quiet (-q) examples to reduce noise; pipe output to jq when you only need the content.
+5. Include your curated file in the agent context whenever you want it to call XcodeBuildMCP via Reloaderoo.
+
+Conventions in the examples:
+- Calls use: npx reloaderoo@latest inspect … -q -- npx xcodebuildmcp@latest
+- Parameters are passed as JSON via --params.
+- Resources are read with read-resource (e.g., xcodebuildmcp://simulators).
+- Use jq -r '.contents[].text' to extract the textual results when needed.
+
+Keep it small. The smaller your curated primer, the less context your agent needs—and the cheaper, faster, and more reliable your interactions will be.
+
+## Installation
+
+Reloaderoo is available via npm and can be used with npx for universal compatibility.
+
+```bash
+# Use npx to run reloaderoo
+npx reloaderoo@latest --help
+```
+
+## Hint
+
+Use jq to parse the output to get just the content response:
+
+```bash
+ npx reloaderoo@latest inspect read-resource "xcodebuildmcp://simulators" -q -- npx xcodebuildmcp@latest | jq -r '.contents[].text'
+ ```
+
+**Example Tool Calls:**
+
+## Dynamic Tool Discovery
+
+- **`discover_tools`**: Analyzes a task description to enable relevant tools.
+  ```bash
+  npx reloaderoo@latest inspect call-tool discover_tools --params '{"task_description": "I want to build and run my iOS app on a simulator."}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## iOS Device Development
+
+- **`build_device`**: Builds an app for a physical device.
+  ```bash
+  npx reloaderoo@latest inspect -q call-tool build_device --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`get_device_app_path`**: Gets the `.app` bundle path for a device build.
+  ```bash
+  npx reloaderoo@latest inspect call-tool get_device_app_path --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`install_app_device`**: Installs an app on a physical device.
+  ```bash
+  npx reloaderoo@latest inspect call-tool install_app_device --params '{"deviceId": "DEVICE_UDID", "appPath": "/path/to/MyApp.app"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`launch_app_device`**: Launches an app on a physical device.
+  ```bash
+  npx reloaderoo@latest inspect call-tool launch_app_device --params '{"deviceId": "DEVICE_UDID", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`list_devices`**: Lists connected physical devices.
+  ```bash
+  npx reloaderoo@latest inspect call-tool list_devices --params '{}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`stop_app_device`**: Stops an app on a physical device.
+  ```bash
+  npx reloaderoo@latest inspect call-tool stop_app_device --params '{"deviceId": "DEVICE_UDID", "processId": 12345}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`test_device`**: Runs tests on a physical device.
+  ```bash
+  npx reloaderoo@latest inspect call-tool test_device --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "deviceId": "DEVICE_UDID"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## iOS Simulator Development
+
+- **`boot_sim`**: Boots a simulator.
+  ```bash
+  npx reloaderoo@latest inspect call-tool boot_sim --params '{"simulatorUuid": "SIMULATOR_UUID"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`build_run_sim`**: Builds and runs an app on a simulator.
+  ```bash
+  npx reloaderoo@latest inspect call-tool build_run_sim --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "simulatorName": "iPhone 16"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`build_sim`**: Builds an app for a simulator.
+  ```bash
+  npx reloaderoo@latest inspect call-tool build_sim --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "simulatorName": "iPhone 16"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`get_sim_app_path`**: Gets the `.app` bundle path for a simulator build.
+  ```bash
+  npx reloaderoo@latest inspect call-tool get_sim_app_path --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "platform": "iOS Simulator", "simulatorName": "iPhone 16"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`install_app_sim`**: Installs an app on a simulator.
+  ```bash
+  npx reloaderoo@latest inspect call-tool install_app_sim --params '{"simulatorUuid": "SIMULATOR_UUID", "appPath": "/path/to/MyApp.app"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`launch_app_logs_sim`**: Launches an app on a simulator with log capture.
+  ```bash
+  npx reloaderoo@latest inspect call-tool launch_app_logs_sim --params '{"simulatorUuid": "SIMULATOR_UUID", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`launch_app_sim`**: Launches an app on a simulator.
+  ```bash
+  npx reloaderoo@latest inspect call-tool launch_app_sim --params '{"simulatorName": "iPhone 16", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`list_sims`**: Lists available simulators.
+  ```bash
+  npx reloaderoo@latest inspect call-tool list_sims --params '{}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`open_sim`**: Opens the Simulator application.
+  ```bash
+  npx reloaderoo@latest inspect call-tool open_sim --params '{}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`stop_app_sim`**: Stops an app on a simulator.
+  ```bash
+  npx reloaderoo@latest inspect call-tool stop_app_sim --params '{"simulatorName": "iPhone 16", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`test_sim`**: Runs tests on a simulator.
+  ```bash
+  npx reloaderoo@latest inspect call-tool test_sim --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme", "simulatorName": "iPhone 16"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## Log Capture & Management
+
+- **`start_device_log_cap`**: Starts log capture for a physical device.
+  ```bash
+  npx reloaderoo@latest inspect call-tool start_device_log_cap --params '{"deviceId": "DEVICE_UDID", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`start_sim_log_cap`**: Starts log capture for a simulator.
+  ```bash
+  npx reloaderoo@latest inspect call-tool start_sim_log_cap --params '{"simulatorUuid": "SIMULATOR_UUID", "bundleId": "com.example.MyApp"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`stop_device_log_cap`**: Stops log capture for a physical device.
+  ```bash
+  npx reloaderoo@latest inspect call-tool stop_device_log_cap --params '{"logSessionId": "SESSION_ID"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`stop_sim_log_cap`**: Stops log capture for a simulator.
+  ```bash
+  npx reloaderoo@latest inspect call-tool stop_sim_log_cap --params '{"logSessionId": "SESSION_ID"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## macOS Development
+
+- **`build_macos`**: Builds a macOS app.
+  ```bash
+  npx reloaderoo@latest inspect call-tool build_macos --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`build_run_macos`**: Builds and runs a macOS app.
+  ```bash
+  npx reloaderoo@latest inspect call-tool build_run_macos --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`get_mac_app_path`**: Gets the `.app` bundle path for a macOS build.
+  ```bash
+  npx reloaderoo@latest inspect call-tool get_mac_app_path --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`launch_mac_app`**: Launches a macOS app.
+  ```bash
+  npx reloaderoo@latest inspect call-tool launch_mac_app --params '{"appPath": "/Applications/Calculator.app"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`stop_mac_app`**: Stops a macOS app.
+  ```bash
+  npx reloaderoo@latest inspect call-tool stop_mac_app --params '{"appName": "Calculator"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`test_macos`**: Runs tests for a macOS project.
+  ```bash
+  npx reloaderoo@latest inspect call-tool test_macos --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## Project Discovery
+
+- **`discover_projs`**: Discovers Xcode projects and workspaces.
+  ```bash
+  npx reloaderoo@latest inspect call-tool discover_projs --params '{"workspaceRoot": "/path/to/workspace"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`get_app_bundle_id`**: Gets an app's bundle identifier.
+  ```bash
+  npx reloaderoo@latest inspect call-tool get_app_bundle_id --params '{"appPath": "/path/to/MyApp.app"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`get_mac_bundle_id`**: Gets a macOS app's bundle identifier.
+  ```bash
+  npx reloaderoo@latest inspect call-tool get_mac_bundle_id --params '{"appPath": "/Applications/Calculator.app"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`list_schemes`**: Lists schemes in a project or workspace.
+  ```bash
+  npx reloaderoo@latest inspect call-tool list_schemes --params '{"projectPath": "/path/to/MyProject.xcodeproj"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`show_build_settings`**: Shows build settings for a scheme.
+  ```bash
+  npx reloaderoo@latest inspect call-tool show_build_settings --params '{"projectPath": "/path/to/MyProject.xcodeproj", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## Project Scaffolding
+
+- **`scaffold_ios_project`**: Scaffolds a new iOS project.
+  ```bash
+  npx reloaderoo@latest inspect call-tool scaffold_ios_project --params '{"projectName": "MyNewApp", "outputPath": "/path/to/projects"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`scaffold_macos_project`**: Scaffolds a new macOS project.
+  ```bash
+  npx reloaderoo@latest inspect call-tool scaffold_macos_project --params '{"projectName": "MyNewMacApp", "outputPath": "/path/to/projects"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## Project Utilities
+
+- **`clean`**: Cleans build artifacts.
+  ```bash
+  # For a project
+  npx reloaderoo@latest inspect call-tool clean --params '{"projectPath": "/path/to/MyProject.xcodeproj"}' -q -- npx xcodebuildmcp@latest
+  # For a workspace
+  npx reloaderoo@latest inspect call-tool clean --params '{"workspacePath": "/path/to/MyWorkspace.xcworkspace", "scheme": "MyScheme"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## Simulator Management
+
+- **`reset_sim_location`**: Resets a simulator's location.
+  ```bash
+  npx reloaderoo@latest inspect call-tool reset_sim_location --params '{"simulatorUuid": "SIMULATOR_UUID"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`set_sim_appearance`**: Sets a simulator's appearance (dark/light mode).
+  ```bash
+  npx reloaderoo@latest inspect call-tool set_sim_appearance --params '{"simulatorUuid": "SIMULATOR_UUID", "mode": "dark"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`set_sim_location`**: Sets a simulator's GPS location.
+  ```bash
+  npx reloaderoo@latest inspect call-tool set_sim_location --params '{"simulatorUuid": "SIMULATOR_UUID", "latitude": 37.7749, "longitude": -122.4194}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`sim_statusbar`**: Overrides a simulator's status bar.
+  ```bash
+  npx reloaderoo@latest inspect call-tool sim_statusbar --params '{"simulatorUuid": "SIMULATOR_UUID", "dataNetwork": "wifi"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## Swift Package Manager
+
+- **`swift_package_build`**: Builds a Swift package.
+  ```bash
+  npx reloaderoo@latest inspect call-tool swift_package_build --params '{"packagePath": "/path/to/package"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`swift_package_clean`**: Cleans a Swift package.
+  ```bash
+  npx reloaderoo@latest inspect call-tool swift_package_clean --params '{"packagePath": "/path/to/package"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`swift_package_list`**: Lists running Swift package processes.
+  ```bash
+  npx reloaderoo@latest inspect call-tool swift_package_list --params '{}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`swift_package_run`**: Runs a Swift package executable.
+  ```bash
+  npx reloaderoo@latest inspect call-tool swift_package_run --params '{"packagePath": "/path/to/package"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`swift_package_stop`**: Stops a running Swift package process.
+  ```bash
+  npx reloaderoo@latest inspect call-tool swift_package_stop --params '{"pid": 12345}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`swift_package_test`**: Tests a Swift package.
+  ```bash
+  npx reloaderoo@latest inspect call-tool swift_package_test --params '{"packagePath": "/path/to/package"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## System Doctor
+
+- **`doctor`**: Runs system diagnostics.
+  ```bash
+  npx reloaderoo@latest inspect call-tool doctor --params '{}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## UI Testing & Automation
+
+- **`button`**: Simulates a hardware button press.
+  ```bash
+  npx reloaderoo@latest inspect call-tool button --params '{"simulatorUuid": "SIMULATOR_UUID", "buttonType": "home"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`describe_ui`**: Gets the UI hierarchy of the current screen.
+  ```bash
+  npx reloaderoo@latest inspect call-tool describe_ui --params '{"simulatorUuid": "SIMULATOR_UUID"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`gesture`**: Performs a pre-defined gesture.
+  ```bash
+  npx reloaderoo@latest inspect call-tool gesture --params '{"simulatorUuid": "SIMULATOR_UUID", "preset": "scroll-up"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`key_press`**: Simulates a key press.
+  ```bash
+  npx reloaderoo@latest inspect call-tool key_press --params '{"simulatorUuid": "SIMULATOR_UUID", "keyCode": 40}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`key_sequence`**: Simulates a sequence of key presses.
+  ```bash
+  npx reloaderoo@latest inspect call-tool key_sequence --params '{"simulatorUuid": "SIMULATOR_UUID", "keyCodes": [40, 42, 44]}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`long_press`**: Performs a long press at coordinates.
+  ```bash
+  npx reloaderoo@latest inspect call-tool long_press --params '{"simulatorUuid": "SIMULATOR_UUID", "x": 100, "y": 200, "duration": 1500}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`screenshot`**: Takes a screenshot.
+  ```bash
+  npx reloaderoo@latest inspect call-tool screenshot --params '{"simulatorUuid": "SIMULATOR_UUID"}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`swipe`**: Performs a swipe gesture.
+  ```bash
+  npx reloaderoo@latest inspect call-tool swipe --params '{"simulatorUuid": "SIMULATOR_UUID", "x1": 100, "y1": 200, "x2": 100, "y2": 400}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`tap`**: Performs a tap at coordinates.
+  ```bash
+  npx reloaderoo@latest inspect call-tool tap --params '{"simulatorUuid": "SIMULATOR_UUID", "x": 100, "y": 200}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`touch`**: Simulates a touch down or up event.
+  ```bash
+  npx reloaderoo@latest inspect call-tool touch --params '{"simulatorUuid": "SIMULATOR_UUID", "x": 100, "y": 200, "down": true}' -q -- npx xcodebuildmcp@latest
+  ```
+- **`type_text`**: Types text into the focused element.
+  ```bash
+  npx reloaderoo@latest inspect call-tool type_text --params '{"simulatorUuid": "SIMULATOR_UUID", "text": "Hello, World!"}' -q -- npx xcodebuildmcp@latest
+  ```
+
+## Resources
+
+- **Read devices resource**:
+  ```bash
+  npx reloaderoo@latest inspect read-resource "xcodebuildmcp://devices" -q -- npx xcodebuildmcp@latest
+  ```
+- **Read simulators resource**:
+  ```bash
+  npx reloaderoo@latest inspect read-resource "xcodebuildmcp://simulators" -q -- npx xcodebuildmcp@latest
+  ```
+- **Read doctor resource**:
+  ```bash
+  npx reloaderoo@latest inspect read-resource "xcodebuildmcp://doctor" -q -- npx xcodebuildmcp@latest
+  ```