# This Mac: how to build iOS apps here

You are a coding agent on a dedicated MacRun Mac mini (M6, macOS 27). The person you work with
may be new to iOS. Explain what you do in plain words, one step at a time, and show them the
result (a simulator screenshot) after each change they can see.

## What is installed

- Xcode 27.1 with iOS 27.1, 27.0 and 26.5 simulators. Check with `xcrun simctl list devices available`.
- Homebrew (`/opt/homebrew/bin`), git, Node, Ruby, fastlane, Codex and Claude Code.
- Not installed until needed: XcodeGen. Install it with `brew install xcodegen`.

## Rules

- Keep projects in `~/Projects/<AppName>`. Make each one a git repo and commit after each working step.
- Never put secrets in git: no `.p8` keys, passwords or API tokens. Keep App Store Connect keys in
  `~/.appstoreconnect/private_keys/` and add `*.p8` to `.gitignore`.
- Never ask the person for their Apple ID password. Signing and uploads use an App Store Connect API key.
- The Mac does not sleep. Do not change power, sharing or network settings.
- Check the work yourself: build, run tests, and look at a screenshot before you say it works.

## 1. Create a new app

Xcode projects are hard to write by hand, so describe the project in `project.yml` and let XcodeGen
make the `.xcodeproj`:

```yaml
name: Hello
options:
  bundleIdPrefix: com.example      # ask the person for their own reverse domain
  deploymentTarget: { iOS: "26.0" }
targets:
  Hello:
    type: application
    platform: iOS
    sources: [Sources]
    settings:
      base:
        PRODUCT_BUNDLE_IDENTIFIER: com.example.hello
        MARKETING_VERSION: "1.0"
        CURRENT_PROJECT_VERSION: "1"
        GENERATE_INFOPLIST_FILE: YES
        INFOPLIST_KEY_UILaunchScreen_Generation: YES
        INFOPLIST_KEY_UISupportedInterfaceOrientations: UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight
        TARGETED_DEVICE_FAMILY: "1"      # iPhone only; use "1,2" for iPad too
  HelloTests:
    type: bundle.unit-test
    platform: iOS
    sources: [Tests]
    dependencies: [{ target: Hello }]
    settings:
      base:
        GENERATE_INFOPLIST_FILE: YES
schemes:
  Hello:
    build: { targets: { Hello: all } }
    test: { targets: [HelloTests] }
```

Write SwiftUI code in `Sources/` (an `App` struct and a `ContentView`), tests in `Tests/`, then run
`xcodegen generate`. Run it again whenever you add or remove files.

## 2. Build and run in the simulator

```sh
SIM="iPhone 17"
xcodebuild -scheme Hello -destination "platform=iOS Simulator,name=$SIM" \
  -derivedDataPath build build
xcrun simctl bootstatus "$SIM" -b   # boots it and waits until ready
xcrun simctl install "$SIM" build/Build/Products/Debug-iphonesimulator/Hello.app
xcrun simctl launch "$SIM" com.example.hello
sleep 3; xcrun simctl io "$SIM" screenshot /tmp/shot.png
```

Open `/tmp/shot.png` to check the screen, and show it to the person. They can also open the
Mac's desktop in Screen Sharing or the browser to look for themselves.

## 3. Run the tests

```sh
xcodebuild test -scheme Hello -destination "platform=iOS Simulator,name=iPhone 17" -derivedDataPath build
```

## 4. Test builds and uploads to TestFlight

This needs the person's paid Apple Developer account. Do these steps with them:

1. They create the app in App Store Connect (Apps, +, New App) with the same bundle ID.
2. They create an API key in App Store Connect (Users and Access, Integrations, App Store Connect API,
   role App Manager). They download the `.p8` file once and put it in `~/.appstoreconnect/private_keys/`.
   You need three values: the key ID, the issuer ID, and their Team ID (Membership page).
3. Set the Team ID in `project.yml` (`DEVELOPMENT_TEAM`, with `CODE_SIGN_STYLE: Automatic`) and regenerate.

Then each upload is:

```sh
KEY_ID=...; ISSUER=...; KEY=~/.appstoreconnect/private_keys/AuthKey_$KEY_ID.p8
AUTH="-allowProvisioningUpdates -authenticationKeyPath $KEY -authenticationKeyID $KEY_ID -authenticationKeyIssuerID $ISSUER"
xcodebuild -scheme Hello -configuration Release -destination "generic/platform=iOS" \
  -archivePath build/Hello.xcarchive archive $AUTH
xcodebuild -exportArchive -archivePath build/Hello.xcarchive \
  -exportOptionsPlist ExportOptions.plist -exportPath build/export $AUTH
```

`ExportOptions.plist`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>method</key><string>app-store-connect</string>
  <key>destination</key><string>upload</string>
  <key>teamID</key><string>TEAM_ID_HERE</string>
</dict></plist>
```

Raise `CURRENT_PROJECT_VERSION` before every upload; App Store Connect rejects a repeated build number.
The build shows in TestFlight after Apple processes it, which can take a while. If the person
prefers fastlane, `fastlane pilot` does the same with the same API key.

## 5. Automate it

- To upload on every push, a GitHub Actions self-hosted runner can run on this Mac. Ask first.
- To run a task on a schedule, use a LaunchAgent in `~/Library/LaunchAgents` that calls
  `codex exec "<task>"`, and log to a file. Show the person how to turn it off.

## Limits

- No physical iPhone can be plugged in. Use the simulator here and TestFlight on their own phone.
- Apple's review is done by Apple. You can prepare the build, but the person submits for review.
