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/apple/homebrew-apple 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.

AVOID — Looks unmaintained — solo project with stale commits

• ⚠ Stale — last commit 2y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{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 apple/homebrew-apple repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/apple/homebrew-apple.

What it runs against: a local clone of apple/homebrew-apple — 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 apple/homebrew-apple | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 4 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 723 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of apple/homebrew-apple. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/apple/homebrew-apple.git
#   cd homebrew-apple
#
# 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 apple/homebrew-apple and re-run."
  exit 2
fi

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

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

# 4. Critical files exist
test -f "Formula/game-porting-toolkit.rb" \\
  && ok "Formula/game-porting-toolkit.rb" \\
  || miss "missing critical file: Formula/game-porting-toolkit.rb"
test -f "Formula/game-porting-toolkit-compiler.rb" \\
  && ok "Formula/game-porting-toolkit-compiler.rb" \\
  || miss "missing critical file: Formula/game-porting-toolkit-compiler.rb"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Formula/COPYING.txt" \\
  && ok "Formula/COPYING.txt" \\
  || miss "missing critical file: Formula/COPYING.txt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 723 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~693d)"
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/apple/homebrew-apple"
  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).

apple/homebrew-apple is an official Homebrew tap (third-party formula repository) maintained by Apple that provides macOS-specific software packages installable via Homebrew package manager. It currently focuses on the Game Porting Toolkit—a compiler and framework that enables developers to port Windows games to macOS by providing DirectX-to-Metal translation and supporting libraries. Simple flat structure: Formula/ directory contains two Ruby formula files (game-porting-toolkit.rb and game-porting-toolkit-compiler.rb) that define Homebrew package metadata and installation logic. Each .rb file is a Homebrew formula using Ruby DSL. No subdirectories, no complex hierarchy—this is a minimal tap with focused scope.

macOS game developers and developers interested in using the Game Porting Toolkit who want to install Apple's gaming tools via Homebrew rather than manual downloads. Also relevant to maintainers of Homebrew who need reference implementations for Apple-supported formulae.

Appears to be in early, actively-maintained status. The repository is minimal (only 2 main formulae visible: game-porting-toolkit and game-porting-toolkit-compiler) with no visible test suite or CI configuration in the file list. As an official Apple repository, it likely has internal testing but the public presence is lean. Production-ready for its narrow scope but not actively feature-rich.

Low risk operationally since this is Apple-maintained and only packages official Apple software. Primary risk is dependency on external Game Porting Toolkit downloads from developer.apple.com (users must manually download separately per README instructions), creating a fragile coupling. Very small surface area (2 formulae) minimizes breaking changes, but lack of visible versioning strategy or changelog means upgrades could be disruptive.

Unknown from provided data. No commit history, PR list, or recent activity indicators are visible. As an official Apple tap, updates likely align with Game Porting Toolkit releases on developer.apple.com, but specific current work is not evident.

brew tap apple/apple
brew install game-porting-toolkit

Note: You must first download the Game Porting Toolkit from https://developer.apple.com/download/all/?q=game%20porting%20toolkit and follow the special instructions in the README before the formula can function.

Daily commands: This is not a runnable project—it is a Homebrew tap. After brew install game-porting-toolkit, the toolkit becomes available as a command-line tool. No dev server or interactive startup required.

• Formula/game-porting-toolkit.rb — Core formula that defines the Game Porting Toolkit package installation and dependencies—entry point for users installing this tap.
• Formula/game-porting-toolkit-compiler.rb — Companion formula providing the compiler toolchain for Game Porting Toolkit—critical for build-time functionality.
• README.md — Documents the tap's purpose, special download requirements, and setup instructions that every contributor and user must follow.
• Formula/COPYING.txt — License and legal terms governing use of these formulae—required reading for compliance and redistribution.

• game-porting-toolkit.rb formula (Ruby, Homebrew DSL) — Declares the main toolkit package, its dependencies (including the compiler), download source, and installation steps
  • Failure mode: If formula is misconfigured, toolkit installation fails or depends on unavailable packages
• game-porting-toolkit-compiler.rb formula (Ruby, Homebrew DSL) — Provides the compiler toolchain as a separate installable component with its own dependencies
  • Failure mode: Compiler unavailability breaks downstream game builds; incorrect version pinning causes incompatibility
• README.md documentation (Markdown) — Communicates special setup requirements (manual download) and tap usage instructions
  • Failure mode: Unclear instructions lead to users attempting full automated installation and encountering licensing errors

• developer.apple.com → User's local Homebrew cache — User manually downloads Game Porting Toolkit binary; Homebrew references cached copy during installation
• homebrew-apple tap (GitHub) → Homebrew package manager — Homebrew clones tap and parses formula files to resolve package definitions and dependencies
• Formula dependencies → game-porting-toolkit installation — Compiler and other declared dependencies are installed before main toolkit installation proceeds

Add a new Game Porting Toolkit formula variant

1. Create a new Ruby file in the Formula directory following naming convention Formula/game-porting-toolkit-*.rb (Formula/)
2. Define the formula class inheriting from Formula, specify version and sha256, and declare dependencies matching existing patterns in game-porting-toolkit.rb (Formula/game-porting-toolkit-*.rb)
3. Implement install and test methods mirroring the structure in existing formulae (Formula/game-porting-toolkit-*.rb)
4. Update README.md with special instructions if the new formula requires manual downloads from developer.apple.com (README.md)

Update Game Porting Toolkit formula to new version

1. Obtain the new version number and sha256 hash from the downloaded toolkit (Formula/game-porting-toolkit.rb)
2. Update the url, version, and sha256 fields in the formula file (Formula/game-porting-toolkit.rb)
3. Review and update any changed dependencies or installation procedures in the install method (Formula/game-porting-toolkit.rb)

Document special setup requirements

1. Review current special instructions in README.md Special Instructions section (README.md)
2. Add new subsection under ### if a formula requires manual steps (e.g., pre-download from developer.apple.com) (README.md)

• Homebrew (Ruby-based package manager) — Provides macOS-native package distribution and dependency management for Game Porting Toolkit and its compiler.
• Ruby formula DSL — Homebrew's declarative formula syntax allows concise definition of dependencies, build steps, and installation procedures.
• GitHub hosting (apple/homebrew-apple tap) — Leverages Homebrew's tap system for version control, community contributions, and transparent formula maintenance.

• Requiring manual pre-download from developer.apple.com rather than automatic fetch

  • Why: Apple's license terms likely prohibit automated redistribution of the toolkit binaries.
  • Consequence: Users must manually download the toolkit first, increasing setup friction but ensuring legal compliance.

• Separate compiler formula (game-porting-toolkit-compiler) vs. bundled in main formula

  • Why: Allows users to install just the compiler independently and supports modular dependency graphs.
  • Consequence: Slightly more complex tap structure but provides flexibility for advanced users and CI/CD pipelines.

• Tap-based distribution (not Homebrew core)

  • Why: Apple-specific tooling would not meet Homebrew core's broad compatibility requirements.
  • Consequence: Users must explicitly add the tap, reducing discoverability but enabling faster release cycles.

• Does not provide automatic binary downloads; users must manually fetch from developer.apple.com
• Does not support Linux or non-macOS platforms
• Does not include source code for Game Porting Toolkit itself—only package definitions
• Does not provide real-time updates or version polling; versioning is manual

• Avg cyclomatic complexity: ~2.5 — Codebase is minimal and straightforward—two Ruby formulae with declarative syntax and a README. Complexity is low due to small scope and declarative nature of Homebrew formulae.
• Largest file: Formula/game-porting-toolkit.rb (45 lines)
• Estimated quality issues: ~1 — No automated version detection or CI/CD pipeline to keep formulae current; manual maintenance is the only update mechanism.

• Manual version pinning without automated update process (Medium) — Formula/game-porting-toolkit.rb, Formula/game-porting-toolkit-compiler.rb: Version numbers and SHA256 hashes are hardcoded; no CI/CD automation detects new releases from Apple, risking stale formulae.
• Reliance on external manual step (pre-download requirement) (Low) — README.md, Formula/game-porting-toolkit.rb: Users must manually download from developer.apple.com before installation, increasing support burden and user error.

• Manual download requirement from developer.apple.com (User experience) — Setup process requires users to manually navigate external site and cache the download, slowing adoption
• Formula maintenance cycle (Operational) — Updates to formulae require manual version and hash updates; no automated tooling to detect new toolkit releases

Critical gotcha: the Game Porting Toolkit must be manually downloaded from developer.apple.com BEFORE installing via Homebrew—the formula cannot auto-download it due to Apple's licensing restrictions. This is buried in the README and requires developers to have an Apple Developer account. Also, the compiler dependency relationship between game-porting-toolkit and game-porting-toolkit-compiler is not obvious from file listing—check both formula files to understand the coupling.

• Homebrew Tap — This entire repository IS a Homebrew tap—understanding taps as third-party formula repositories is essential to understanding the project's purpose and structure
• Homebrew Formula DSL — The .rb files use Homebrew's Ruby-based formula language; you must understand this DSL to modify or add packages to this tap
• DirectX-to-Metal Translation — The Game Porting Toolkit's core capability translates Windows DirectX calls to macOS Metal; understanding this abstraction layer is key to knowing what this toolkit actually does
• Binary Packaging and Checksums — Homebrew formulae define sha256 checksums for downloaded binaries to verify integrity; modifying packages requires recalculating these checksums
• Dependency Graph in Package Management — The compiler formula is a dependency of the toolkit formula; understanding how Homebrew resolves transitive dependencies is critical for managing the two-formula relationship

• Homebrew/homebrew-core — The main Homebrew formula repository that provides most standard packages; this apple tap extends it with Apple-specific tools
• Homebrew/brew — The core Homebrew package manager that executes these formulae; understanding brew's architecture is essential for tap development
• microsoft/vcpkg — Alternative package management approach for Windows/C++ development; relevant as comparative packaging strategy for gaming toolchains
• apple/swift — Another official Apple open-source repository using similar Homebrew distribution patterns for developer tools

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 SHA256 checksum verification for game-porting-toolkit downloads

The README requires users to manually download Game Porting Toolkit from developer.apple.com. The formulae (game-porting-toolkit.rb and game-porting-toolkit-compiler.rb) should include SHA256 checksum validation to ensure downloaded files haven't been tampered with and match expected versions. This is a critical security practice for Homebrew formulae, especially when handling large binary files from external sources.

• [ ] Add sha256 field to game-porting-toolkit.rb with documented checksum
• [ ] Add sha256 field to game-porting-toolkit-compiler.rb with documented checksum
• [ ] Update README.md with instructions on how to verify/find checksums for different GPT versions
• [ ] Document in comments which GPT version each checksum corresponds to

Create install/uninstall test scripts for game-porting-toolkit formulae

There are no visible test files for the two main formulae. Add test scripts that verify: (1) successful installation and dependency resolution for game-porting-toolkit.rb, (2) successful installation for game-porting-toolkit-compiler.rb, and (3) proper cleanup on uninstall. This helps catch regressions and ensures the tap works across macOS versions.

• [ ] Create test/game_porting_toolkit_test.rb following Homebrew test conventions
• [ ] Add tests verifying game-porting-toolkit-compiler.rb installs without errors
• [ ] Add test verifying required dependencies are present post-install
• [ ] Document how to run tests locally in README.md

Add version management and download URL documentation to formulae

The formulae likely need to specify or document which Game Porting Toolkit versions they support, and provide clearer guidance on version compatibility. Add version constraints, supported macOS versions, and create a VERSIONS.md file documenting breaking changes or version-specific requirements between different GPT releases.

• [ ] Add depends_on :macos => constraints to both formula files specifying minimum macOS version
• [ ] Create VERSIONS.md documenting supported Game Porting Toolkit versions and their download URLs
• [ ] Add comments in game-porting-toolkit.rb and game-porting-toolkit-compiler.rb indicating compatible GPT versions
• [ ] Update README.md with a version compatibility matrix

• Add integration tests for the formulae (create spec/ or test/ directory with tests verifying the formulae install correctly and binaries are discoverable post-installation)
• Document the manual download process more clearly with screenshots and step-by-step instructions in a SETUP.md guide, since the README.md instruction is terse
• Add version constraint testing: create a script that validates the formulae work with multiple recent macOS versions and report compatibility matrix in documentation

The homebrew-apple tap demonstrates reasonable security practices as a Homebrew formula repository. The primary concern is the manual download requirement for game-porting-toolkit, which bypasses standard verification mechanisms. The repository lacks visible security documentation and a defined vulnerability disclosure process. No hardcoded secrets, injection vulnerabilities, or infrastructure misconfigurations are evident from the available information. Further detailed analysis of the Ruby formula implementations is recommended to identify potential command injection or unsafe system call patterns.

• Medium · Manual Download Requirement for Game Porting Toolkit — README.md, Formula/game-porting-toolkit.rb. The game-porting-toolkit formula requires users to manually download software from developer.apple.com before installation. This approach bypasses the standard Homebrew verification mechanisms and could potentially expose users to supply chain risks if they download from unofficial sources or if the download process is intercepted. Fix: Implement automated signature verification of downloaded files. Consider using Homebrew's built-in download and verification mechanisms. Provide clear documentation on verifying file checksums and signatures.
• Low · Limited Code Review Visibility — Formula/game-porting-toolkit-compiler.rb, Formula/game-porting-toolkit.rb. The partial file structure shows only formula definitions and a COPYING.txt file. Without visibility into the actual Ruby formula implementations, potential vulnerabilities in how they handle dependencies, execute commands, or process user input cannot be fully assessed. Fix: Conduct thorough code review of both formula files, specifically checking for: unsafe shell command execution, improper input validation, insecure file permissions, and unsafe use of system calls.
• Low · Missing Security Documentation — Repository root. No security policy, vulnerability disclosure process, or security guidelines are visible in the provided repository structure. This could hinder responsible security research and vulnerability reporting. Fix: Add a SECURITY.md file documenting: responsible disclosure process, how to report security issues, security contact information, and security best practices for users.

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.