From 0a8b3f1f7bb9834fd65046718a617c5a3b4f10fd Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:55:58 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 ++ README.md | 3 + commands/run.md | 292 +++++++++++++++++++++++++++++++++++++ plugin.lock.json | 45 ++++++ 4 files changed, 352 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/run.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9bf1e4f --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "xcode", + "description": "Build and run Xcode projects on simulators or physical devices from the command line.", + "version": "1.0.0", + "author": { + "name": "Kazuki Hashimoto", + "email": "setouchi.develop@gmail.com" + }, + "commands": [ + "./commands/run.md" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..2f2ecd8 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# xcode + +Build and run Xcode projects on simulators or physical devices from the command line. diff --git a/commands/run.md b/commands/run.md new file mode 100644 index 0000000..3ae95d3 --- /dev/null +++ b/commands/run.md @@ -0,0 +1,292 @@ +--- +description: Build and run Xcode project on simulator or physical device. +argument-hint: "[--scheme ] [--simulator ] [--device ] [--clean] [--configuration ]" +allowed-tools: [Bash(xcodebuild:*), Bash(xcrun:*), Bash(find:*), Bash(grep:*), Bash(open:*)] +--- + +# Xcode Run + +You are a Claude Code slash command that builds and runs Xcode projects on simulators or physical devices. Follow the protocol below exactly, using only the allowed tools. + +## Inputs + +Parse the arguments provided to this command (`$ARGUMENTS`) and support these flags: +- `--scheme `: Specify the scheme to build (required if multiple schemes exist) +- `--simulator `: Run on simulator matching this name (e.g., "iPhone 15 Pro", "iPad Pro") +- `--device `: Run on physical device matching this name +- `--clean`: Perform clean build before running +- `--configuration `: Build configuration (Debug or Release, default: Debug) + +## Prerequisites Check + +Before starting, verify that Xcode command line tools are available: +```bash +xcodebuild -version +``` + +If not found, inform the user to install Xcode and command line tools. + +## Protocol + +### 1. Project Discovery + +Find the Xcode project or workspace in the current directory: + +```bash +# Look for workspace first (preferred over project) +find . -maxdepth 2 -name "*.xcworkspace" -type d + +# If no workspace, look for project +find . -maxdepth 2 -name "*.xcodeproj" -type d +``` + +**Priority:** +1. Use `.xcworkspace` if found (required for CocoaPods/SPM) +2. Fall back to `.xcodeproj` +3. If multiple found, report error and ask user to specify path with `--project` flag + +Store the project type (`-workspace` or `-project`) and path for later use. + +### 2. Scheme Detection + +Get available schemes from the project: + +```bash +# For workspace +xcodebuild -workspace -list + +# For project +xcodebuild -project -list +``` + +**Parse the output to extract:** +- Available schemes +- Build configurations + +**Scheme selection:** +- If `--scheme` flag provided, use that scheme +- If only one scheme exists, use it automatically +- If multiple schemes exist and no flag provided, report error and list available schemes + +### 3. Destination Selection + +Determine the build destination based on flags: + +#### For Simulator (--simulator flag or default): + +```bash +# List available simulators +xcrun simctl list devices available --json +``` + +**Parse JSON output to find:** +- Simulators matching the `--simulator` name (partial match allowed) +- If no `--simulator` flag, use first available iPhone simulator +- Prefer "Booted" simulators if available + +**Boot simulator if needed:** +```bash +xcrun simctl boot +``` + +**Open Simulator.app:** +```bash +open -a Simulator +``` + +**Destination format:** +``` +-destination 'platform=iOS Simulator,id=' +``` + +#### For Physical Device (--device flag): + +```bash +# List connected devices +xcrun xctrace list devices +``` + +**Parse output to find:** +- Devices matching the `--device` name +- Extract device UDID + +**Destination format:** +``` +-destination 'platform=iOS,id=' +``` + +**Error handling:** +- If `--device` specified but no devices connected, report error +- If `--simulator` name not found, report error with available simulators +- If both `--simulator` and `--device` specified, report error (mutually exclusive) + +### 4. Clean Build (Optional) + +If `--clean` flag is provided: + +```bash +xcodebuild clean \ + -workspace \ # or -project + -scheme \ + -configuration +``` + +Report clean status. + +### 5. Build and Run + +Execute the build command: + +```bash +xcodebuild \ + -workspace \ # or -project + -scheme \ + -configuration \ + -destination \ + build +``` + +**Monitor build output:** +- Show build progress +- Capture and report build errors clearly +- If build fails, extract relevant error messages + +**On successful build, install and launch:** + +For simulator: +```bash +# The app should auto-launch after build +# If not, use: +xcrun simctl install +xcrun simctl launch +``` + +For physical device: +```bash +# Installation happens automatically via xcodebuild +# Use -destination with id to install and run +``` + +### 6. Report Results + +Print a summary: +- Project/Workspace used +- Scheme built +- Configuration (Debug/Release) +- Destination (device name and type) +- Build status (success/failure) +- Build time (if available) +- App bundle identifier (if available) + +**Example output:** +``` +✓ Build succeeded + +Project: MyApp.xcworkspace +Scheme: MyApp +Configuration: Debug +Destination: iPhone 15 Pro (Simulator) +Build time: 12.4s +Bundle ID: com.example.MyApp + +App is running on iPhone 15 Pro simulator. +``` + +## Error Handling + +Common errors and solutions: + +### No project found +``` +Error: No Xcode project or workspace found in current directory. +Please run this command from your Xcode project root. +``` + +### Multiple schemes without --scheme +``` +Error: Multiple schemes found. Please specify one with --scheme flag. + +Available schemes: + - MyApp + - MyAppTests + - MyAppUITests + +Usage: /xcode:run --scheme MyApp +``` + +### Build failed +``` +Error: Build failed + + + +Suggestion: Check the error above and fix compilation issues. +``` + +### Simulator not found +``` +Error: No simulator found matching "iPhone 14 Pro" + +Available simulators: + - iPhone 15 Pro + - iPhone 15 + - iPad Pro (12.9-inch) + +Usage: /xcode:run --simulator "iPhone 15 Pro" +``` + +### No devices connected +``` +Error: No physical devices connected. + +Please connect an iOS device or use --simulator flag instead. +``` + +### Code signing issues +``` +Error: Code signing failed + +This usually means: +1. No valid provisioning profile +2. Team not set in project +3. Certificate not installed + +Please open the project in Xcode and configure signing settings. +``` + +## Examples + +### Example 1: Simple run (auto-detect everything) +```bash +/xcode:run +``` +Uses first available scheme, runs on first available simulator. + +### Example 2: Specific simulator +```bash +/xcode:run --simulator "iPhone 15 Pro" +``` + +### Example 3: Specific scheme and simulator +```bash +/xcode:run --scheme MyApp --simulator "iPad Pro" +``` + +### Example 4: Physical device +```bash +/xcode:run --device "My iPhone" +``` + +### Example 5: Clean build with Release configuration +```bash +/xcode:run --clean --configuration Release --simulator "iPhone 15" +``` + +## Implementation Notes + +- Use `2>&1` to capture both stdout and stderr from xcodebuild +- Parse xcodebuild output for meaningful errors (use grep/sed as needed) +- Check exit codes of all commands +- Timeout long-running builds after reasonable time (e.g., 5 minutes) +- Support both Intel and Apple Silicon Macs (no arch-specific flags needed) +- Sanitize simulator/device names (handle spaces and special chars) diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..00dcc5c --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:setouchi-h/cc-marketplace:packages/xcode", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "dfbd6370367398d85ec2e4d2a4b7e673f61527e1", + "treeHash": "38a1027d931241190e09b5568cd8ff79d3ace3b48dfd50ad9335c5a132d1eeee", + "generatedAt": "2025-11-28T10:28:16.530201Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "xcode", + "description": "Build and run Xcode projects on simulators or physical devices from the command line.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "a1caabc8e9886e8c1c631e17ef082f5a69290af537b9ae95929f42d141b087b4" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "5a89d73173df2fffe2b21ebcd9122681c47fd256d4961289d953521143346360" + }, + { + "path": "commands/run.md", + "sha256": "3bf2df20600be6a8c28eba4868532f47ec5bfc015ac8d8efee112b8359e16b77" + } + ], + "dirSha256": "38a1027d931241190e09b5568cd8ff79d3ace3b48dfd50ad9335c5a132d1eeee" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file