If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/xcpretty/xcode-install shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 27+ active contributors
• Distributed ownership (top contributor 14% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live xcpretty/xcode-install repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/xcpretty/xcode-install.

What it runs against: a local clone of xcpretty/xcode-install — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in xcpretty/xcode-install | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 765 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of xcpretty/xcode-install. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/xcpretty/xcode-install.git
#   cd xcode-install
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of xcpretty/xcode-install and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "xcpretty/xcode-install(\\.git)?\\b" \\
  && ok "origin remote is xcpretty/xcode-install" \\
  || miss "origin remote is not xcpretty/xcode-install (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/xcode/install.rb" \\
  && ok "lib/xcode/install.rb" \\
  || miss "missing critical file: lib/xcode/install.rb"
test -f "lib/xcode/install/cli.rb" \\
  && ok "lib/xcode/install/cli.rb" \\
  || miss "missing critical file: lib/xcode/install/cli.rb"
test -f "bin/xcversion" \\
  && ok "bin/xcversion" \\
  || miss "missing critical file: bin/xcversion"
test -f "lib/xcode/install/command.rb" \\
  && ok "lib/xcode/install/command.rb" \\
  || miss "missing critical file: lib/xcode/install/command.rb"
test -f "lib/xcode/install/install.rb" \\
  && ok "lib/xcode/install/install.rb" \\
  || miss "missing critical file: lib/xcode/install/install.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 765 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~735d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/xcpretty/xcode-install"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

xcode-install is a Ruby gem that automates downloading and installing Xcode versions from Apple's Developer Center. It parses the developer.apple.com/download/more/ page, handles authentication via credentials_manager, and provides CLI commands (xcversion install/list/select) to manage multiple Xcode installations on macOS. The project is now sunset but remains a reference implementation for Apple developer tool automation. Single Ruby gem structure: lib/xcode/install.rb is the core coordinator, lib/xcode/install/ contains command classes (cli.rb, install.rb, list.rb, select.rb, uninstall.rb, update.rb, etc.), bin/xcversion is the CLI entry point. Spec fixtures in spec/fixtures/ mock Apple Developer pages (devcenter/*.html) and JSON responses for testing.

macOS developers and CI/CD engineers who need to programmatically manage multiple Xcode versions across team machines or build infrastructure. Particularly useful for teams using fastlane workflows that require specific Xcode versions per project.

This project is sunset and actively being deprecated (see MIGRATION.md in repo root). It has a working test suite (spec/*.rb with fixtures), CI via GitHub Actions (.github/workflows/ci.yml), and was maintained by xcpretty maintainers, but is no longer receiving active updates. The README explicitly warns users to migrate to alternatives.

High risk for new projects: The project is officially deprecated with a migration guide. Additional risks include transitive native extension dependencies (domain_name gem), reliance on Apple's developer portal HTML scraping (brittle to page changes), single-maintainer history, and no updates post-sunset announcement. Environment variables XCODE_INSTALL_USER and XCODE_INSTALL_PASSWORD require Apple Developer credentials to function.

The project is in sunset/maintenance mode. The README states 'This project is being sunset' with a reference to MIGRATION.md. No active development is occurring; the repo is preserved for reference. CI pipeline (.github/workflows/ci.yml) still runs but likely passes on legacy tests only.

Clone and install: git clone https://github.com/xcpretty/xcode-install.git && cd xcode-install && gem install bundler && bundle install. Run tests: bundle exec rake or bundle exec rspec spec/. For local usage: gem build xcode-install.gemspec && gem install xcode-install-*.gem.

Daily commands: After bundle install, run bin/xcversion list (requires XCODE_INSTALL_USER and XCODE_INSTALL_PASSWORD env vars) or bundle exec rspec to run the test suite against fixtures.

• lib/xcode/install.rb — Main entry point and orchestrator for the xcode-install gem; defines the core Xcode class used by all commands.
• lib/xcode/install/cli.rb — CLI command dispatcher and argument parser; all user-facing commands route through this layer.
• bin/xcversion — Executable entry point invoked by users; delegates to CLI module.
• lib/xcode/install/command.rb — Abstract base class for all command subclasses; defines the shared interface and error handling.
• lib/xcode/install/install.rb — Core installation logic; handles downloading and mounting Xcode .xip files from Apple servers.
• lib/xcode/install/list.rb — Fetches and parses available Xcode versions from Apple Developer downloads page; critical for version discovery.

• CLI (cli.rb) (Thor (implicit), Ruby optparse patterns) — Parses command-line arguments and routes to subcommands; handles global options like --verbose.
  • Failure mode: Invalid arguments → exits with usage help; subcommand not found → exits with error.
• Command base class (command.rb) (Ruby inheritance, exception handling) — Abstract parent for all subcommands; provides error handling, logging, and Xcode instance management.
  • Failure mode: Missing credentials → raises error; subprocess failures → propagates with context.
• Xcode core (install.rb) (curl/REST, HTML parsing, credential mgmt) — Orchestrates Apple API calls, credential verification, version queries, and download operations.
  • Failure mode: Auth failure → re-prompts

Add a new install subcommand

1. Create a new command class inheriting from Command in lib/xcode/install/ (lib/xcode/install/command.rb)
2. Implement the run method with your command logic (lib/xcode/install/mycommand.rb)
3. Register the command in the CLI dispatcher (lib/xcode/install/cli.rb)
4. Add test coverage in spec/ directory following existing patterns (spec/mycommand_spec.rb)

Add support for a new Xcode version format or source

1. Extend or override the version parsing logic in the Xcode class (lib/xcode/install.rb)
2. Update list command to handle new format (lib/xcode/install/list.rb)
3. Add fixture data in spec/fixtures/ for new version format (spec/fixtures/devcenter/)
4. Write parsing tests (spec/json_spec.rb)

Enhance authentication or credential handling

1. Review current credential management in main Xcode class (lib/xcode/install.rb)
2. Implement new auth mechanism as a method in the Xcode class (lib/xcode/install.rb)
3. Update CLI to accept new credential parameters if needed (lib/xcode/install/cli.rb)
4. Add integration tests with mock Apple Developer endpoints (spec/cli_spec.rb)

• Ruby & Thor/CLI — Lightweight, cross-platform command-line framework; enables scriptable Xcode management without native dependencies.
• HTML/CSS scraping (nokogiri implicit) — Apple Developer Downloads page is dynamic; parsing HTML fixtures and live pages is the only reliable way to discover available versions.
• curl/libcurl (shell invocation) — Low-level HTTP client for downloading large .xip files; integrates with system SSL/auth infrastructure.
• RSpec for testing — Standard Ruby testing framework; fixtures of HTML pages and JSON enable offline, deterministic test coverage.

• HTML scraping for version discovery instead of official API

  • Why: Apple does not publish a public API for Xcode downloads; scraping is the only available integration point.
  • Consequence: Brittle to Apple UI changes; requires regular fixture updates and maintenance.

• Blocking, synchronous downloads with no resume support

  • Why: Simplifies CLI UX; all operations complete before returning control to shell.
  • Consequence: Large files (10–15 GB) tie up terminal; network interruptions restart entire download.

• Credential storage in environment variables / keychain

  • Why: Avoids plaintext file storage; integrates with OS security.
  • Consequence: Requires user to manage credentials outside tool; breaks in CI/CD without special setup.

• Project sunset / no active maintenance

  • Why: Apple's official command-line tools (xcode-select, softwareupdate) have improved; maintaining a web-scraping workaround is unsustainable.
  • Consequence: Users directed to migration guide; no new features or version support.

• Does not manage Xcode beta versions or release candidates beyond parsing from Apple's page.
• Does not provide GUI installer; CLI-only tool.
• Does not automate simulator installation at scale (limited support via simulators command).
• Does not support Linux or Windows; macOS-only (requires xcode-select, hdiutil).
• Does not offer official API for version discovery; relies on undocumented Apple Developer page structure.

Critical: Requires XCODE_INSTALL_USER and XCODE_INSTALL_PASSWORD environment variables; without them, authentication to Apple Developer Center will fail silently in some paths. Brittleness: The HTML scraper in lib/xcode/install.rb parses Apple's developer.apple.com/download/more/ page by regex/CSS selectors; any page layout change breaks version listing. Native deps: domain_name gem dependency requires a C compiler; pre-built gem workaround documented in README. Xcode mounting: Uses hdiutil and sudo for mounting .xip files; requires admin privileges and specific macOS setup. Sunset: Project is officially deprecated; Apple's new App Store approach may break this entirely.

• Credential Manager Pattern — xcode-install delegates credential storage to fastlane's credentials_manager; understanding how sensitive data (XCODE_INSTALL_USER, XCODE_INSTALL_PASSWORD) flows through the system is critical for security
• HTML Scraping & Web Parsing — Core of xcode-install: parses Apple Developer page structure via CSS selectors and regex to extract Xcode version metadata; brittle but necessary for version discovery
• Command Pattern (OOP) — lib/xcode/install/command.rb defines abstract command base; each subcommand (install.rb, list.rb, select.rb) implements the pattern, making CLI extensible and testable
• XIP (Apple Installer Package) Format — Xcode is distributed as .xip files; xcode-install must extract and mount these using hdiutil; understanding XIP is essential for the install.rb flow
• macOS Disk Utility / hdiutil — install.rb uses hdiutil command-line tool to mount Xcode .app disk images; understanding macOS volume mounting is necessary to debug installation failures
• Ruby Gems & Native Extensions — xcode-install has transitive dependency on domain_name gem with C extensions; understanding Ruby gem compilation and workarounds (pre-built gem download in README) is practical knowledge
• Fixture-Driven Testing — spec/fixtures/ contains mock HTML pages from Apple Developer site; tests run against these fixtures rather than live requests, ensuring reproducibility and speed; critical for understanding test strategy

• fastlane/fastlane — xcode-install uses fastlane's credentials_manager for secure credential storage; fastlane is the canonical macOS build automation framework
• xcpretty/xcpretty — Sister project by same maintainers; formats Xcode build output, often used alongside xcode-install in CI pipelines
• Homebrew/homebrew-cask — Alternative approach: Homebrew Cask can install Xcode versions via cask files, though less flexible than xcode-install for version selection
• RobotsAndPencils/xcodes — Modern Swift-based successor to xcode-install with better maintenance and native Apple Notarization support; recommended migration target
• mas-cli/mas — Complementary tool for managing App Store applications on macOS, often used to install Xcode from Mac App Store in newer workflows

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for lib/xcode/install/simulators.rb

The simulators.rb command exists in the file structure but has no corresponding test file (no spec/simulators_spec.rb). This is a critical gap given the project's test-driven approach with existing specs for install, installed, list, uninstall, etc. Adding tests would ensure the simulators command works correctly and prevent regressions.

• [ ] Create spec/simulators_spec.rb with test fixtures for simulator output parsing
• [ ] Add unit tests for simulator list parsing and filtering logic in lib/xcode/install/simulators.rb
• [ ] Add integration test cases for the xcversion simulators CLI command in spec/cli_spec.rb
• [ ] Ensure test coverage matches existing patterns from spec/installed_spec.rb and spec/list_spec.rb

Add test coverage for lib/xcode/install/cleanup.rb command

The cleanup.rb module exists but there is no corresponding spec/cleanup_spec.rb test file. This is particularly important for a cleanup operation that likely modifies the file system. Comprehensive tests would prevent accidental data loss bugs.

• [ ] Create spec/cleanup_spec.rb with mock file system operations
• [ ] Add unit tests for cleanup logic (e.g., identifying old Xcode installations, deletion safety checks)
• [ ] Add test cases for edge cases (insufficient permissions, in-use Xcode, missing installations)
• [ ] Add integration test for the xcversion cleanup CLI command in spec/cli_spec.rb

Add GitHub Actions workflow for testing on macOS with actual Xcode versions

The existing .github/workflows/ci.yml likely runs on Linux or has limited macOS testing. Since this tool directly interacts with Xcode installations, macOS-specific integration tests are needed. Add a dedicated workflow that tests on macOS runners to catch platform-specific issues before release.

• [ ] Create .github/workflows/macos-integration.yml for macOS-specific testing
• [ ] Configure workflow to run on multiple macOS versions (latest stable and one previous version)
• [ ] Add test steps for verifying Xcode detection, installation paths, and simulator listing on actual macOS
• [ ] Include a test for parsing actual hdiutil output and mounting behavior specific to macOS
• [ ] Ensure workflow runs on pull requests and main branch pushes

• Add test coverage for lib/xcode/install/selected.rb and lib/xcode/install/simulators.rb which have no visible spec files in spec/ directory
• Document the .xcode-version file format and parsing logic in a separate spec file (spec/xcode_version_spec.rb) with fixtures for various version formats (beta, GM, release versions)
• Create integration test fixtures for lib/xcode/install/cleanup.rb logic by mocking hdiutil and xattr outputs in spec/fixtures/ and adding spec/cleanup_spec.rb

This is a sunset project with significant security concerns. The most critical issue is the lack of active maintenance - users will be vulnerable to any future security issues in dependencies. Additionally, the incomplete information provided (missing gemspec details, CI/CD configuration, and actual source code review) prevents a comprehensive assessment. The tool handles Apple Developer credentials and downloads executable software, which requires careful security practices. Immediate risks include unmaintained dependencies, unclear credential handling, and test fixture data management. Users should migrate to actively maintained alternatives, and the project should be formally archived with clear deprecation notices.

• High · Project Sunset - Maintenance Risks — README.md, MIGRATION.md. The project is explicitly marked as being sunset according to MIGRATION.md. This means the codebase is no longer actively maintained, which poses significant security risks. Future vulnerabilities discovered in dependencies will not be patched, and security issues may remain unaddressed. Fix: Users should migrate to an actively maintained alternative. Project maintainers should archive the repository and add clear deprecation notices.
• High · Native Extension Dependency Risk — README.md, xcode-install.gemspec. The README indicates XcodeInstall has a transitive dependency on a gem with native extensions (ruby-domain_name). This requires compilation and increases the attack surface through C/C++ code that may contain buffer overflows or memory safety issues. The incomplete curl command in README suggests manual workarounds. Fix: Review the gemspec dependencies and consider replacing native extension gems with pure Ruby alternatives. Ensure all transitive dependencies are pinned to specific versions and regularly audited.
• High · Missing Dependency Specification — xcode-install.gemspec. The dependency/package file content is not provided. Without visibility into gemspec dependencies and versions, it's impossible to assess if vulnerable gem versions are being used. This is critical for a tool that installs development software. Fix: Provide complete gemspec with explicit version constraints. Run bundle audit regularly and use tools like Dependabot to track vulnerabilities.
• Medium · Credential Exposure Risk in Apple Developer Downloads — lib/xcode/install.rb, lib/xcode/install/cli.rb. The tool authenticates with Apple Developer portal (Downloads for Apple Developer page) to download Xcodes. While no hardcoded credentials are visible, the authentication mechanism and credential storage should be carefully reviewed. Fix: Ensure credentials are stored in secure credential storage (macOS Keychain), never in plain text or environment variables. Implement OAuth/token-based authentication if possible.
• Medium · Incomplete Security Configuration — Project root. No .env.example or security configuration documentation is visible. The tool handles authentication and downloads which require secure defaults. Fix: Add .env.example file documenting required configurations and security best practices. Document credential handling in SECURITY.md.
• Medium · Test Fixtures with Sensitive HTML — spec/fixtures/devcenter/, spec/fixtures/mail-verify.html. Fixture files include real HTML snapshots from developer.apple.com and credential-related test data (mail-verify.html, not_registered_as_developer.json). These could inadvertently contain sensitive information patterns. Fix: Sanitize all fixture files to remove any potentially sensitive information. Use synthetic/mock data instead of real website snapshots.
• Medium · CI/CD Pipeline Not Reviewed — .github/workflows/ci.yml. CI/CD workflow exists (.github/workflows/ci.yml) but content is not provided for security review. This could be a vector for credential exposure or supply chain attacks. Fix: Review CI/CD configuration for: 1) Secrets management (use GitHub Secrets, not plaintext), 2) Branch protection rules, 3) Code signing practices for releases, 4) Dependency verification.
• Low · Unusual File Name in Bin Directory — bin/🎉. A file named '🎉' exists in the bin directory. While likely harmless, non-standard file names can obscure intent and potentially cause issues with build systems or deployment scripts. Fix: Rename to a standard ASCII filename with clear purpose. Ensure all executable scripts have proper shebangs and permissions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.