tart-xcode-runner
/tart-xcode-runner
Uruchamia dowolne polecenie, build lub test w jednorazowej maszynie wirtualnej macOS Tart, zwłaszcza testy UI i XCUITest.
- Autor
- novotnyllc ↗
- Repozytorium
- tart-xcode-runner ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 08.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 14
- Skrypty
- 6
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 08.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 6 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: references/prepare-image.zsh, references/provision-image.sh, references/run-command.sh, references/run-xcode.sh, references/setup-developer-id.zsh, references/upgrade-macos.sh
Co robi i kiedy
Uruchamia dowolne polecenie, build lub test w jednorazowej maszynie wirtualnej macOS Tart, zwłaszcza testy UI i XCUITest.
Wyzwalacze z opisu
Oryginalny opis (EN)
Run any command, build, or test in a disposable macOS virtual machine (Tart). Use whenever the user wants work run in a VM, sandbox, container, clean room, or fresh/isolated/ephemeral/disposable environment, off-host, "not on my machine", or without polluting their system — especially xcodebuild, Xcode builds, unit tests, UI tests, XCUITests, iOS/macOS/simulator work, or trying something risky safely. ALWAYS use this by default for UI tests, XCUITests, and simulator-based test runs — even when the user doesn't mention a VM — because host UI automation steals their screen, keyboard, and focus.
Jak działa
- Setup
- Match the VM to the project
- Run
- Recover or update
- Multiple golden images
- Cleanup
- Configuration reference
- Storage
Podgląd SKILL.md
---
name: tart-xcode-runner
description: Run any command, build, or test in a disposable macOS virtual machine (Tart). Use whenever the user wants work run in a VM, sandbox, container, clean room, or fresh/isolated/ephemeral/disposable environment, off-host, "not on my machine", or without polluting their system — especially xcodebuild, Xcode builds, unit tests, UI tests, XCUITests, iOS/macOS/simulator work, or trying something risky safely. ALWAYS use this by default for UI tests, XCUITests, and simulator-based test runs — even when the user doesn't mention a VM — because host UI automation steals their screen, keyboard, and focus. Also use to prepare, update, reset, roll back, or fetch logs and xcresult bundles from the test VM. Use when the user asks to create, request, install, verify, back up, or restore a macOS Developer ID Application certificate or signing identity, including Developer ID provisioning, restricted entitlements, Keychain access, or 1Password custody.
---
# Tart Xcode Runner
UI tests, XCUITests, and simulator test runs go in the VM by default, without
being asked: on the host they seize the user's display, keyboard, and focus
while they work. Run them on the host only if the user explicitly insists
after being warned.
Installed plugins expose their root as `CLAUDE_PLUGIN_ROOT` (Claude Code) or
`CODEX_PLUGIN_ROOT` (Codex); from a source checkout, run commands at the
repository root instead. Set:
```sh
PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-.}}
RUNNER=$PLUGIN_ROOT/skills/tart-xcode-runner/references/tart-runner
IMAGE_BUILDER=$PLUGIN_ROOT/skills/tart-xcode-runner/references/prepare-image.zsh
DEVELOPER_ID_SETUP=$PLUGIN_ROOT/skills/tart-xcode-runner/references/setup-developer-id.zsh
```
## Setup
1. Install and trust OpenAI's Homebrew tap:
```sh
brew tap openai/tools
brew trust --tap openai/tools
brew install openai/tools/tart
```
2. Run `"$RUNNER" doctor`. If the execution sandbox cannot inspect the login
keychain or start Virtualization.framework, request host authorization for
the runner. Never fall back to running UI tests on the host.
3. Pick the image config. Precedence, first match wins:
1. A config checked into the project being tested: `.tart-xcode/image.json`
at the repo root. Honor it without asking.
2. The user explicitly asks for a beta or a specific OS/Xcode version.
3. The project requires beta SDKs (deployment target or SDK newer than the
current stable) → `"$PLUGIN_ROOT/config/image-27-beta.json"`.
4. Otherwise the stable default: `"$PLUGIN_ROOT/config/image-26.5.json"`.
Then build or update the golden image from it:
```sh
"$IMAGE_BUILDER" rebuild "$CONFIG"
```
With no argument, `rebuild` uses `TART_XCUI_IMAGE_CONFIG` or the stable
default. To pin an image for a project, copy a shipped config into that
repo as `.tart-xcode/image.json` and edit it — commit it so every machine
reconstructs the same VM.
Always run `rebuild` before considering any build: it validates the
current golden image against the config and no-ops when it already
matches — the image may already exist from a previous session. Follow the
config's checked-in `buildStrategy`; do not pick a strategy yourself:
- `download` (stable default): clone the pinned published OCI seed image
and validate it. Fast; no local Xcode app needed.
- `upgrade` (beta default): clone the pinned preconfigured seed, apply the
pinned `InstallAssistant.pkg`, and install the configured host Xcode app,
runtimes, CLI selection, license, Metal toolchain, and login settings —
preserving guest agent, SSH, auto-login, and no-lock setup. Requires the
beta Xcode app on the host at `xcodeApp` (Apple developer login needed to
download it). There is no interactive Setup Assistant.
The seed does NOT need to match the target macOS: `upgrade` exists
precisely to build a newer macOS (a 27 beta) on top of the newest
published seed (a 26.x image). "No published image for the target
version" is the normal case `upgrade` solves, never a reason to fall
back to `packer`.
- `packer`: build from a restore IPSW. Slow (hours) and heavy; use only
when no seed image of any version can boot the target at all — a new
device family or a seed-incompatible major release, both rare. Never
choose it just because the exact target version has no published seed.
Direct commands also exist: `"$IMAGE_BUILDER" download OCI_IMAGE` promotes
a published image (validated against the config first), and
`"$IMAGE_BUILDER" packer --config CONFIG` runs the from-IPSW build; the
packer path is unattended, bounded by `TART_XCUI_PACKER_TIMEOUT` (one hour
default), and needs Packer and Go
(`brew tap hashicorp/tap && brew install hashicorp/tap/packer go`).
All paths build a candidate, validate it, then replace the powered-off golden
base. Never delete the current base before candidate validation succeeds.
Repeat `--platform` to preload optional runtimes such as `tvOS`, `watchOS`, or
`visionOS`. iOS is the default when no platform is supplied.
Add runtimes later without rebuilding macOS or Xcode:
```sh
"$IMAGE_BUILDER" add-platform tvOS
```
This modifies a disposable clone and promotes it only after validation.
For a durable, reconstructible change, also add the platform to the active
config (the project's `.tart-xcode/image.json` if present) and run
`"$IMAGE_BUILDER" rebuild "$CONFIG"`.
The golden base also selects Xcode's CLI tools, completes first-launch tasks,
accepts the license, installs the Metal toolchain, enables auto-login, and
disables sleep, screensavers, and screen locking.
### Optional macOS Developer ID setup
The current runner does not automate a Developer ID build/sign/return lane.
Setup alone does not make entitlement-dependent tests pass. Keep using the
credential-free ad-hoc path unless the project genuinely exercises a restricted
entitlement such as Keychain Sharing. This helper manages macOS Developer ID
Application identities only; Developer ID does not sign iOS apps.
When the user asks for signing setup, run the read-only preflight first:
```sh
"$DEVELOPER_ID_SETUP" status
```
If Keychain inspection is denied or indeterminate, request host authorization
and rerun `status`; never interpret that failure as a missing identity or offer
to consume another certificate slot. When setup is actually approved, run the
guided command in one attached, persistent PTY or tmux session:
```sh
"$DEVELOPER_ID_SETUP" setup
```
Keep that entire invocation in the same session so the user can complete
Keychain Access, Apple, `codesign`, and 1Password authorization prompts. The
helper fails instead of silently skipping work when no terminal is attached.
It opens the human-only CSR and Apple certificate steps, imports the resulting
certificate, requires the exact certificate fingerprint to pair with its
private key, and signs and strictly verifies a disposable executable before
reporting success.
The 1Password CLI is required for backup; the desktop app is optional because
the helper also supports CLI-only sign-in. Without the desktop app, configure
the intended account once with `op account add` before running the helper. When
the CLI is present, the helper offers a backup and validates that the exported
`.p12` is encrypted, contains a matching private key, and holds a trusted
Developer ID Application certificate. It then creates one item in the
explicitly selected account and restricted vault containing the encrypted
archive plus its concealed export password, downloads both, and round-trip
validates them. Record the printed item ID; restore requires that unambiguous
ID and repeats exact-fingerprint validation and the signing probe. Run
`"$DEVELOPER_ID_SETUP" --help` for separate `enroll`, `probe`, `store-p12`,
and `restore-p12` commands.
Before implementing the build/sign/return lane, follow
[Profile-backed macOS entitlements](../../README.md#profile-backed-macos-entitlements).
It is the canonical operator procedure for CSR and profile creation, 1Password
transfer, multiple hosts, Keychain readiness, and certificate-slot tradeoffs.
A Developer ID identity stays on approved signing hosts: never put a private
key, `.p12`, password, Apple credential, or API key in the repository, golden
image, guest share, VM, or test artifacts. Do not register the VM or sign an
Apple Account into the guest.
The implementation must preserve or reconstruct every product's fully expanded
entitlements, embed each matching profile, sign nested code inside-out without
`codesign --deep`, and return the products to the same guest for
`test-without-building`. Prove a real protected operation through app relaunch,
including strict signature, entitlement, and `ProvisionsAllDevices` checks,
before reporting the lane as supported.
## Match the VM to the project
Before running project work, detect what the project needs and provision the
VM to match — never ask the user to do this manually:
1. Inspect the checkout on the host: `SDKROOT`, destinations, and platform
names in `*.pbxproj`, schemes, and `Package.swift`
(`appletvos`/`tvOS` → tvOS, `watchos` → watchOS, `xros`/`visionOS` →
visionOS; Metal shader compilation → MetalToolchain). iOS and macOS are
always present in the base image.
2. If extra platforms are needed, check what the VM already has:
```sh
"$RUNNER" run -- /usr/bin/xcrun simctl list runtimes available
```
3. Install anything missing, then proceed:
```sh
"$RUNNER" add-platform tvOS
"$RUNNER" add-component MetalToolchain
```
If a run still fails with a missing-runtime or missing-SDK error, install the
named platform the same way and retry once. Dependencies fetched by the build
itself (SwiftPM, CocoaPods via `--repo` copy) need no VM changes — they
resolve inside the disposable clone.
## Run
Run an arbitrary command in a disposable clone:
```sh
"$RUNNER" run -- /usr/bin/sw_vers
"$RUNNER" run --repo /absolute/path/to/repo -- /bin/zsh -lc 'make check'
```
`--repo` mounts the checkout read-only, copies it to guest APFS, and runs from
that copy. The command receives `TART_SOURCE` and `TART_ARTIFACTS`.
Run an Xcode build:
```sh
"$RUNNER" build --repo /absolute/path/to/repo -- \
-workspace App.xcworkspace -scheme App build
```
Run an XCUITest:
```sh
"$RUNNER" xcui-test --repo /absolute/path/to/repo -- \
-workspace App.xcworkspace \
-scheme AppUITests \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=latest' \
test
```
Omit `-destination` to use the first available iPhone simulator. Pass an
explicit destination for macOS tests or when device choice matters.
Signing is handled automatically on the credential-free path: the VM has no
signing identities, so when no `CODE_SIGN*`, `DEVELOPMENT_TEAM`, or
`PROVISIONING_PROFILE*` argument is supplied, the guest applies ad-hoc manual
signing with entitlements dropped (verified: macOS UI tests pass with no
signing arguments). Passing signing arguments only disables that fallback; it
does not expose host identities to the guest. Never pass
`CODE_SIGNING_ALLOWED=NO` for UI tests — the unsigned test runner hangs before
connecting.
Ad-hoc signing cannot authorize profile-backed entitlements. Until the
host-signing round-trip above is implemented and proven for the project,
exclude those tests with `-only-testing:`/`-skip-testing:` and say so in the
report rather than reporting a false failure. Never copy a Developer ID
identity into the VM as a shortcut.
Report the printed result directory and exit status. Inspect `command.log` or
`xcodebuild.log`; use `xcrun xcresulttool` against `Result.xcresult` for
structured failures. Never make the source share writable or build on VirtioFS.
## Recover or update
- Run `"$RUNNER" reset` after an interrupted invocation. It removes only the
disposable clone and preserves the powered-off base. If `doctor` reports a
host-crash quarantine, inspect the named panic or login-session crash report
first. Only then may the user explicitly authorize
`"$RUNNER" reset --acknowledge-host-crash`; never infer that acknowledgement
or clear the quarantine automatically.
- Run `"$RUNNER" rollback` to swap the golden base with the previous validated
image. Each promotion preserves one rollback image (`<base>-previous`).
- Set `TART_XCUI_KEEP_FAILED=1` for one run when interactive inspection is
necessary; reset it afterward.
- Run `"$IMAGE_BUILDER" download OCI_IMAGE` to validate and promote a different
published image.
- Run `"$RUNNER" smoke` after changing the runner, guest scripts, Tart, or
the base image.
Runs may execute in parallel: each gets its own disposable clone, and the
host lock covers only the brief clone step. Budget CPU and RAM — each VM
takes its configured share. Image operations (`prepare`, `add-*`, `reset`,
`rollback`, rebuilds) are exclusive and refuse to start while runs are
active; retry them after the runs finish.
## Multiple golden images
`TART_XCUI_BASE_VM` selects the golden image; candidate, previous, and
work VM names derive from it. Keep one base per image config when projects
need different OS or Xcode versions:
```sh
export TART_XCUI_BASE_VM=tart-xcui-base-26 # this project targets macOS 26
"$IMAGE_BUILDER" rebuild "$PLUGIN_ROOT/config/image-26.5.json"
"$RUNNER" xcui-test --repo /path/to/repo -- -scheme App test
```
Another project can use `TART_XCUI_BASE_VM=tart-xcui-base-27` with the beta
config; both images coexist in the same store, each with its own rollback.
Pair the variable with the project's pinned `.tart-xcode/image.json` so the
same shell sets both. The default base (`tart-xcui-base`) stays for
single-image setups.
## Cleanup
Disk grows in four places: OCI/IPSW caches under `TART_HOME/cache` (tens of
GB), the rollback image (`<base>-previous`, as big as the base), installer
and Xcode archives in `vm-share/cache`, and per-run logs/results. Reclaim
space with:
```sh
"$RUNNER" clean # stale VMs, state logs, caches unused 30 days
"$RUNNER" clean --results 14 # also drop result bundles older than 14 days
"$RUNNER" clean --images # also drop the rollback image and archives
```
`clean` is exclusive (refuses while runs are active) and never touches the
golden base. `--images` trades safety for space: rollback becomes
unavailable until the next promotion, and a future rebuild re-downloads
installers. Suggest `clean` to the user when `doctor` shows the disk running
low; ask before using `--images`.
Superseded versions age out on their own where it's safe: promoting a new
image auto-deletes older pinned installers and Xcode archives (re-downloadable,
keyed by build), and each base keeps exactly one rollback — promoting beta 5
retires beta 4's rollback. Whole golden images are never auto-deleted: when
`clean` lists a base VM whose last access is old (a stable base no project
uses anymore), ask the user before removing it and its `-previous` with
`tart delete`.
## Configuration reference
All knobs are environment variables; defaults in parentheses:
- `TART_XCUI_DATA_HOME` — root for all mutable data (checkout, or
`~/Library/Application Support/Tart Xcode Runner`)
- `TART_XCUI_TART_HOME` — VM disk storage only (`$DATA_HOME/.tart`)
- `TART_XCUI_RESULTS` — result bundles (`$DATA_HOME/results`)
- `TART_XCUI_BASE_VM` — golden image to use (`tart-xcui-base`); derived:
`<base>-candidate`, `<base>-previous`, `<base>-packed`
- `TART_XCUI_IMAGE_CONFIG` — default config for `rebuild`
(`config/image-26.5.json`)
- `TART_XCUI_CPU`, `TART_XCUI_MEMORY` (MB), `TART_XCUI_DISK_SIZE` (GB) —
resources applied by `prepare` when the config doesn't set them
(8 / 24576 / 150); config values win on rebuilds
- `TART_XCUI_RUN_TIMEOUT` — per-run watchdog seconds (7200)
- `TART_XCUI_MAX_REPO_FILES` — maximum source files and symlinks accepted
before any Tart command starts (100000); generated `.build`, `DerivedData*`,
and result trees are excluded from this count and from the guest copy
- `TART_XCUI_READY_TIMEOUT` — VM boot wait seconds (300)
- `TART_XCUI_PACKER_TIMEOUT`, `TART_XCUI_UPGRADE_TIMEOUT` — image build
ceilings (3600 / 7200)
- `TART_XCUI_KEEP_FAILED=1` — retain a failed run's VM for inspection
- `TART_XCUI_GUEST_PASSWORD` — guest admin password (`admin`)
- `TART_XCUI_IMAGE` — OCI image for a bare `prepare` (pinned 26.5 digest)
- `TART_XCUI_RUNS_WAIT` — how long image operations wait for active runs
to drain before giving up (1800)
## Storage
From a source checkout, VM disks and mutable data stay in its Git-ignored
`.tart/`, `results/`, `vm-share/`, and `.state/` directories. From an installed
plugin, they stay across plugin upgrades under
`~/Library/Application Support/Tart Xcode Runner/`. Set
`TART_XCUI_DATA_HOME` to move all mutable data together, or
`TART_XCUI_TART_HOME` to move only Tart's VM storage.
Claude Code and Codex installs both default to the same Application Support
store, so they share golden images. A source checkout is the exception —
its store is separate from any installed plugin's. Before building any image, run `"$RUNNER" doctor` — it
prints the active `TART_HOME` and whether the base VM exists. If the base is
"missing" but a golden image was built before, look for another store (a
plugin checkout's `.tart/`, or the Application Support path) and reuse it via
`TART_XCUI_DATA_HOME` instead of rebuilding for hours.
Pliki w paczce (14)
- SKILL.md 17 KB
- agents/openai.yaml 1 KB
- references/automation-mode.expect 1 KB
- references/macos-beta.pkr.hcl 7 KB
- references/packer-plugin-tart-coordinate-click.patch 2 KB
- references/prepare-image.zsh 21 KB
- references/provision-image.sh 5 KB
- references/run-command.sh 1 KB
- references/run-xcode.sh 2 KB
- references/setup-developer-id.zsh 22 KB
- references/tart-guest-agent.plist 1 KB
- references/tart-guest-daemon.plist 1 KB
- references/tart-runner 24 KB
- references/upgrade-macos.sh 1 KB
Wersje
W bazie nie ma innych skilli o nazwie tart-xcode-runner.
Migawka bazy z 13.11.2026 · wersja paczki 3a30e92f6181 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100macos-vm-testing
Testuje cel macOS projektu, czyli .app, DMG lub instalator, w jednorazowych maszynach wirtualnych Tart na Apple Silicon. - 100xcodebuild
Buduje, testuje i archiwizuje aplikacje iOS i macOS przez xcodebuild i narzędzia CLI Xcode: integracja z CI, schematy, symulatory i diagnozowanie buildów. - 93tart-ci
Buduje szybki, odizolowany pas CI dla macOS na Tart: złote obrazy VM, jednorazowe runnery i cache. - 100install-xcode-vm
Instaluje starszy Xcode z pliku XIP do maszyny wirtualnej macOS, opcjonalnie z symulatorami iOS, i zapisuje gotową migawkę. - 90xcode-simulator-testing
Buduje aplikację iOS dla wskazanego schematu Xcode albo bieżącego i uruchamia ją w symulatorze, bez regeneracji projektu. - 100ios-build-test
Buduje aplikację iOS, uruchamia ją na symulatorze, testuje, nagrywa wideo z symulatora i resetuje aplikację lub onboarding, korzystając z Xcode.