build(setup): preflight Metal before setup mutations

CONTRIBUTING.md

@@ -5,6 +5,23 @@
 - macOS 14+
 - Xcode 26 (the pinned toolchain); Xcode 16.2 on Intel Macs running macOS 14 also builds the macOS app (best effort)
 - [Zig](https://ziglang.org/) (install via `brew install zig`)
+- [Rust](https://rustup.rs) — `scripts/setup.sh` requires `rustup`, and every app build compiles
+  the bundled `cmux-cua` engine with `cargo`. The official installer puts both in `~/.cargo/bin`,
+  which is where `setup.sh` looks:
+
+  ```bash
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+  ```
+
+  Homebrew's `rustup` formula works too, but it is keg-only and no longer ships `rustup-init`, so
+  add `$(brew --prefix rustup)/bin` to `PATH` and run `rustup default stable` yourself.
+- On Xcode 26 the Metal compiler is a separately downloaded component, and the build fails
+  without it. Select the intended full Xcode installation first (`DEVELOPER_DIR`, if
+  exported, overrides `xcode-select`), then install the component:
+
+  ```bash
+  xcodebuild -downloadComponent MetalToolchain
+  ```
 
 ## Getting Started
 
@@ -21,7 +38,9 @@
 
    This will:
    - Initialize git submodules (ghostty, homebrew-cmux)
-   - Build the GhosttyKit.xcframework from source
+   - Install the pinned Rust toolchain
+   - Fetch a checksum-pinned prebuilt GhosttyKit.xcframework, falling back to building it
+     from source with Zig (force the source build with `CMUX_GHOSTTYKIT_NO_PREBUILT=1`)
    - Create the necessary symlinks
 
 3. Build the debug app:

scripts/setup.sh

@@ -6,6 +6,26 @@ PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
 
 cd "$PROJECT_DIR"
 
+# Xcode 26 ships the Metal compiler as a separately downloaded component rather
+# than inside Xcode.app. Without it the app target fails partway through the
+# build ("cannot execute tool 'metal' due to missing Metal Toolchain"), after
+# the Swift modules have already compiled. Fail here instead, where the fix is
+# one command. Older Xcode bundles metal, so this check simply passes there.
+# The Command Line Tools do not ship metal at all, so the message names both
+# causes rather than assuming the component is merely missing.
+echo "==> Checking for the Metal toolchain..."
+if ! xcrun metal --version &> /dev/null; then
+    echo "Error: the Metal compiler is not available."
+    echo "Active developer directory: $(xcode-select -p 2>/dev/null || echo 'unset')"
+    echo "For Xcode 26 or later, install the toolchain component:"
+    echo "    xcodebuild -downloadComponent MetalToolchain"
+    echo "If it is the Command Line Tools, select Xcode first:"
+    echo "    sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer"
+    echo "If DEVELOPER_DIR is exported, unset it or point it to the intended Xcode;"
+    echo "it overrides the system selection."
+    exit 1
+fi
+
 echo "==> Initializing submodules..."
 git submodule update --init --recursive
 
@@ -47,7 +67,9 @@ rustup run "$DIFF_RUST_TOOLCHAIN" rustc --version
 echo "==> Checking for cargo (bundled cmux-cua)..."
 if ! command -v cargo &> /dev/null || ! cargo --version &> /dev/null; then
     echo "Error: a working Rust toolchain (cargo) is required to build the bundled cmux-cua."
-    echo "Install via rustup: https://rustup.rs (or \`brew install rustup && rustup-init\`)"
+    echo "Install via rustup: https://rustup.rs"
+    echo "(Homebrew's rustup is keg-only and ships no rustup-init: add"
+    echo " \"\$(brew --prefix rustup)/bin\" to PATH, then run \`rustup default stable\`.)"
     exit 1
 fi