build(setup): preflight Metal before setup mutations

[austinywang]

Contributor setup can fail late because Metal and Rust prerequisites are missing. This follow-up to #12107 carries forward SangHun Lee (@nrhys2005)'s prerequisite documentation, corrected Homebrew rustup guidance, and Metal probe, preserving both original commits and authorship.

The Metal probe now runs before submodule initialization and Rust installation. Its recovery instructions explain that an exported DEVELOPER_DIR overrides the system selection, and limit component-download guidance to Xcode 26+. The existing xcode-select diagnostic is retained: the review finding claiming it ignores DEVELOPER_DIR was withdrawn. Current main's Xcode 26 / Intel Xcode 16.2 guidance is preserved.

Validation performed on Linux:

• bash -n scripts/setup.sh passed.
• git diff --check passed.
• python3 scripts/swift_file_length_budget.py passed (0 changed Swift files).
• Executed setup.sh with isolated stubs for xcrun, xcode-select, and git: available Metal reaches the submodule sentinel; missing Metal exits 1 before mutations for default Xcode, Command Line Tools, and a custom path containing spaces. The sentinel stops execution before real setup or builds.
• Localization audit covered CONTRIBUTING.md and developer-only shell diagnostics. They remain English-only; no app/web catalog strings changed.

Builds were not run. No compilation, xcodebuild, reload, local/remote/cloud builds, app launches, or dogfood was performed. Stub checks establish shell control flow only; actual Apple toolchain behavior and end-to-end macOS setup remain unverified for this follow-up.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Note

Low Risk
Developer-only setup script and documentation changes; no app runtime, auth, or production build pipeline behavior is altered.

Overview
Setup now fails fast on a missing Metal compiler before submodules, Rust installs, or other setup side effects. scripts/setup.sh runs xcrun metal --version up front and prints targeted recovery steps (MetalToolchain download on Xcode 26+, switching off Command Line Tools, and DEVELOPER_DIR overriding xcode-select).

Contributor docs and Rust/cargo errors are tightened in CONTRIBUTING.md and setup.sh: Rust/rustup and Xcode 26 Metal prerequisites are documented; setup steps now mention the pinned Rust toolchain and checksum-pinned GhosttyKit with a source-build override; Homebrew rustup guidance replaces the outdated rustup-init hint when cargo is missing.

^{Reviewed by Cursor Bugbot for commit 76050fd. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Carries forward the Metal toolchain preflight and prerequisite documentation from #12107 so setup fails early with clear recovery steps instead of failing during builds.

• Checks for the Metal compiler via xcrun metal before any submodule init or Rust install.
• Recovery messages explain both the missing MetalToolchain component on Xcode 26+ and Command Line Tools lacking Metal, and note that exported DEVELOPER_DIR overrides xcode-select.
• Adds Rust and Metal prerequisites to CONTRIBUTING.md, including corrected Homebrew rustup guidance (keg-only, no rustup-init).
• Updates the GhosttyKit build note to mention the checksum-pinned prebuilt framework with a source-build fallback (force with CMUX_GHOSTTYKIT_NO_PREBUILT=1).

^{Written for commit b686b38. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation

  • Updated contributor setup instructions with Rust toolchain requirements and Metal compiler setup guidance.
  • Documented downloading a prebuilt GhosttyKit framework, with an option to build it from source.

• Bug Fixes

  • Added clearer setup validation and remediation messages for missing Metal and Rust tooling.
  • Improved guidance for configuring PATH when Rust is installed through Homebrew.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
cmux166	Ready	Preview	Sep 12, 2026 10:57pm UTC
cmux41	Ready	Preview	Sep 12, 2026 10:57pm UTC

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 03166277-c809-4407-8390-93da56f61dd0

📥 Commits

Reviewing files that changed from the base of the PR and between c006e64 and 76050fd.

📒 Files selected for processing (2)

• CONTRIBUTING.md
• scripts/setup.sh

Included review availability: Your plan provides up to 10 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The setup documentation now covers Rust, Metal, and GhosttyKit requirements. The setup script validates the Metal compiler and provides expanded Rust installation guidance.

Changes

Toolchain setup

Layer / File(s)	Summary
Toolchain requirements and Metal validation CONTRIBUTING.md, scripts/setup.sh	The documentation lists Rust and Metal prerequisites. The setup script checks xcrun metal --version and reports remediation steps when the compiler is unavailable.
Rust setup and GhosttyKit guidance CONTRIBUTING.md, scripts/setup.sh	The documentation describes pinned Rust setup and checksum-pinned GhosttyKit downloads with a Zig fallback. The cargo error explains the Homebrew rustup PATH setup.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Bug fix

Suggested reviewers: lawrencecchen

Merge Risk: ⚪ Minimal · up to b686b

No confirmed merge-blocking risk remains in the toolchain setup changes.

🚥 Pre-merge checks | ✅ 25

✅ Passed checks (25 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a Metal preflight before setup mutations.
Description check	✅ Passed	The description provides a clear summary, detailed testing results, and explicit limitations. It omits the template's Demo Video, Review Trigger, and Checklist sections, but the core required informat…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Cmux Swift Actor Isolation	✅ Passed	PASS: The reviewed range changes only CONTRIBUTING.md and scripts/setup.sh. The authoritative diff contains no .swift or .swiftinterface changes, so it introduces no Swift actor-isolation issue. The S…
Cmux Swift Blocking Runtime	✅ Passed	PASS: The pull request changes only CONTRIBUTING.md and scripts/setup.sh. The authoritative diff contains no Swift files or Swift hunks, and no added blocking or timing primitives. The Swift blocking-…
Cmux Browser Automation Off-Main	✅ Passed	PASS. The authoritative pull-request diff changes only CONTRIBUTING.md and scripts/setup.sh. It adds Rust/Metal setup documentation and a Metal toolchain preflight. It does not change browser sock…
Cmux Expensive Synchronous Load	✅ Passed	The pull request changes only CONTRIBUTING.md and scripts/setup.sh; the authoritative diff contains no Swift files or production Swift changes. Therefore it does not add or move any synchronous ag…
Cmux Cache Substitution Correctness	✅ Passed	PASS: The authoritative PR diff changes only CONTRIBUTING.md and scripts/setup.sh. It contains no Swift, TypeScript, or JavaScript production changes, and it does not replace an authoritative persiste…
Cmux No Hacky Sleeps	✅ Passed	The changed files are CONTRIBUTING.md and scripts/setup.sh. The added setup logic performs one synchronous xcrun metal --version probe and exits on failure; it introduces no sleep, timer, poll…
Cmux Algorithmic Complexity	✅ Passed	PASS. The authoritative diff changes only CONTRIBUTING.md and scripts/setup.sh. Per the repository rule, the shell change adds one xcrun metal --version probe and bounded diagnostic commands; it add…
Cmux Swift Concurrency	✅ Passed	PASS: The authoritative pull-request diff changes only CONTRIBUTING.md and scripts/setup.sh; it changes no Swift files. The shell changes add Metal and Rust prerequisite checks and messages, with …
Cmux Swift @Concurrent	✅ Passed	PASS: The pull request changes only CONTRIBUTING.md and scripts/setup.sh. The authoritative diff contains no .swift paths and no Swift code changes. Therefore the Swift @concurrent check is not applic…
Cmux Swift Package Boundaries	✅ Passed	PASS: The authoritative pull-request diff changes only CONTRIBUTING.md and scripts/setup.sh. It contains no Swift or Swift package source changes, so it cannot introduce an app-target feature that vio…
Cmux Swiftpm Lockfiles	✅ Passed	PASS. The authoritative PR diff changes only CONTRIBUTING.md and scripts/setup.sh. It does not change a Package.swift, Package.resolved, .gitignore, workflow, cmux.xcodeproj package refere…
Cmux Swift Logging	✅ Passed	PASS — The authoritative PR diff changes only CONTRIBUTING.md and scripts/setup.sh. It adds no production Swift files or Swift logging statements. The new shell echo lines are CLI setup output, whic…
Cmux User-Facing Error Privacy	✅ Passed	PASS — The pull request changes CONTRIBUTING.md and the developer-only scripts/setup.sh. The added Xcode, MetalToolchain, DEVELOPER_DIR, rustup, and Homebrew details are contributor documentation and …
Cmux Full Internationalization	✅ Passed	PASS: The PR changes only CONTRIBUTING.md and scripts/setup.sh. The added prose documents contributor setup, and the added shell messages are developer-only setup diagnostics. The rule explicitly …
Cmux Swiftui State Layout	✅ Passed	PASS: The authoritative pull-request diff changes only CONTRIBUTING.md and scripts/setup.sh. It adds documentation and shell setup diagnostics. It contains no Swift source or SwiftUI state/layout chan…
Cmux Architecture Rethink	✅ Passed	PASS. The authoritative PR diff changes only CONTRIBUTING.md and scripts/setup.sh. It contains no Swift, SwiftUI, or AppKit architecture changes. The rule's failure conditions for timing repairs, extr…
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	PASS: The authoritative PR diff changes only CONTRIBUTING.md and scripts/setup.sh. It contains no Swift changes and introduces or materially changes no NSWindow, NSPanel, window controller, SwiftUI Wi…
Cmux Source Artifacts	✅ Passed	The PR changes only CONTRIBUTING.md and the hand-written executable scripts/setup.sh. The diff adds prerequisite documentation and setup diagnostics. It adds no logs, screenshots, recordings, temp…
Cmux No Test Or Debug Seam In Production Source	✅ Passed	The authoritative pull-request diff changes only CONTRIBUTING.md and scripts/setup.sh. It contains no changed Swift files and no changed production path matching **/Sources/**. Therefore, this c…
Cmux No Ambient Global State	✅ Passed	PASS: The authoritative PR diff changes only CONTRIBUTING.md and scripts/setup.sh. It adds documentation and Bash prerequisite checks. It contains no production Swift files or Swift declarations, …

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch followup-pr12107

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}