leepokai avatar

swiftui-smart-build

Auto-install iOS apps after xcodebuild + SwiftUI best practices

version
2.7.1
GitHub stars
7

Install

/plugin install swiftui-smart-build@leepokai

Run it inside Claude Code after adding the marketplace with /plugin marketplace add leepokai/swiftui-smart-build.

Contents

Discovered from source

Skills 1

Smart Build Workflow

Automated build workflow for iOS development with syntax checking, auto-formatting, and instant deployment.


Quick Start

1. Check Preferences (REQUIRED FIRST STEP)

find . -maxdepth 1 -name ".smart-build.json"

⚠️ CRITICAL: If no file is found in the project root:

  • You MUST run the setup flow in @../../references/setup-flow.md BEFORE proceeding
  • DO NOT skip this step - build will fail without proper preferences
  • DO NOT guess or hardcode values - follow the interactive setup

If .smart-build.json exists → Extract scheme and udid, then proceed to step 2

2. LSP Quick Check (Optional, Recommended for Large Changes)

Use LSP to verify types BEFORE building - faster than waiting for xcodebuild to fail.

After adding/modifying functions:

LSP hover on new function signature → verify return type resolves

After renaming symbols:

LSP findReferences on renamed symbol → verify all call sites updated

After importing new modules:

LSP hover on imported type → verify module is available

Example:

// You just added this function
func fetchUser(id: String) -> User { ... }
LSP hover at "fetchUser" → Returns "(String) -> User" ✓ types correct
LSP hover at "User" → Returns "struct User" ✓ type exists

If LSP returns error or empty → fix before building.

3. Build

xcodebuild \
  -scheme "SAVED_SCHEME" \
  -destination "platform=iOS Simulator,id=SAVED_UDID" \
  build

4. Auto-Deploy (Hook)

When build succeeds, hook automatically:

  1. Boots target simulator (if needed)
  2. Installs app
  3. Launches app

Automatic Hooks

Swift Lint Check (on Edit/Write .swift)

  • swiftc -parse - instant syntax check
  • swiftformat - auto-fix style (when syntax OK)

Auto-Install (on xcodebuild success)

  • Extracts UDID from destination (PRIORITY 0)
  • Boots simulator if needed
  • Installs and launches app

Simulator Selection Priority:

PRIORITY 0: UDID from destination (id=XXXX)
PRIORITY 1: Booted simulator matching name
PRIORITY 2: Any booted simulator
PRIORITY 3: Available simulator matching name
PRIORITY 4: First available iPhone

Preferences Validator (on Edit/Write .smart-build.json)

Validates JSON syntax and required fields.


Commands

CommandDescription
/simulator-build-boot-installBuild with saved preferences
/simulator-build-boot-install reviseRevise settings (runs setup flow)
/device-build-boot-installBuild for physical device

Workflow Summary

┌─────────────────────────────────────────────────┐
│  During Editing (Automatic)                     │
│  Edit .swift → swiftc -parse → swiftformat      │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│  Pre-Build (Optional LSP Check)                 │
│  LSP hover → verify types                       │
│  LSP findReferences → verify no broken refs     │
└─────────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────┐
│  Build & Deploy (Automatic)                     │
│  xcodebuild → Boot → Install → Launch           │
└─────────────────────────────────────────────────┘

Troubleshooting (Only When User Requests)

Do NOT proactively run troubleshooting steps. Only use when user explicitly asks to debug or check logs.

# Check logs
cat /tmp/swiftui-smart-build/swift-lint-check.log
cat /tmp/swiftui-smart-build/post-build-install.log
cat /tmp/swiftui-smart-build/validate-preferences.log
ProblemSolution
Hook not triggeringwhich jq - install if missing
Wrong simulator/simulator-build-boot-install revise
No install after buildCheck post-build-install.log

Commands 2

Device: Build → Install → Launch

Build for physical iOS device with saved preferences.

Prerequisites

  1. Device connected via USB or Wi-Fi
  2. Device trusted on this Mac
  3. Signing configured in Xcode (Team + Bundle ID)

Workflow

Step 1: Check for saved preferences

find . -maxdepth 1 -name ".smart-build.json"

If no file is found OR no device section in preferences: → Run the setup flow in @../references/setup-flow.md (device only needs scheme selection)

If device preferences exist: → Go to Step 2

Step 2: Build with saved preferences

Read preferences from .smart-build.json in the project root and run:

xcodebuild \
  -scheme "<SAVED_SCHEME>" \
  -destination "generic/platform=iOS" \
  -allowProvisioningUpdates \
  build
# e.g., xcodebuild -scheme "App-DebugRemote" -destination "generic/platform=iOS" -allowProvisioningUpdates build

What Happens After Build

When build succeeds, the post-build hook automatically:

  1. Detects connected device
  2. Installs the app via devicectl
  3. Launches the app

Do NOT run install or launch commands yourself. The post-build hook handles everything automatically. Your job ends after a successful xcodebuild — never attempt to install or launch the app manually.

Check Connected Devices

xcrun devicectl list devices

Troubleshooting (Only When User Requests)

Do NOT proactively run troubleshooting steps. Only use when user explicitly asks to debug.

IssueSolution
No device foundCheck USB connection, trust the Mac on device
Signing errorOpen Xcode, configure Team in Signing & Capabilities
Install failsEnsure device is unlocked, check provisioning profile

Simulator: Build → Boot → Install

Build for iOS Simulator with saved preferences.

Workflow

Step 1: Check for saved preferences

find . -maxdepth 1 -name ".smart-build.json"

If no file is found OR no simulator section in preferences: → Run the setup flow in @../references/setup-flow.md

If simulator preferences exist: → Go to Step 2

Step 2: Build with saved preferences

Read preferences from .smart-build.json in the project root and run:

xcodebuild \
  -scheme "<SAVED_SCHEME>" \
  -destination "platform=iOS Simulator,id=<SAVED_UDID>" \
  build
# e.g., xcodebuild -scheme "App-DebugLocal" -destination "platform=iOS Simulator,id=24A2580F-BABB-49D2-91EA-2B14498A4246" build

What Happens After Build

When build succeeds, the post-build hook automatically:

  1. Boots the simulator (if not running)
  2. Installs the app
  3. Launches the app

Do NOT run boot, install, or launch commands yourself. The post-build hook handles everything automatically. Your job ends after a successful xcodebuild — never attempt to boot the simulator, install, or launch the app manually.

Sponsors

Details

Marketplace
leepokai/swiftui-smart-build
Source
plugin
Author
leepokai
Category
Development
License
MIT
Keywords
swift, swiftui, xcode, ios, build, simulator, deploy, best-practices