Pets

Appearance

Homebrew Deployment Guide ​

Publishing OpenPets to Homebrew for macOS and Linux users.

🍺 Package Information ​

Package Name: openpetsFormula Location: homebrew-tap/openpets.rbTap Repository: raggle-ai/homebrew-pets

Installation Command:

bash
brew tap raggle-ai/pets
brew install openpets

🚀 Initial Setup ​

1. Create Homebrew Tap Repository ​

Run the automated setup script:

bash
cd homebrew-tap
./setup-tap.sh

This will:

  • Initialize git repository
  • Create GitHub repo at raggle-ai/homebrew-pets
  • Push formula to GitHub

Manual Setup (Alternative) ​

bash
cd homebrew-tap

# Initialize git
git init
git add .
git commit -m "Initial commit: OpenPets formula"

# Create GitHub repository
gh repo create raggle-ai/homebrew-pets \
  --public \
  --description "Homebrew tap for OpenPets" \
  --homepage "https://pets.raggle.co"

# Push to GitHub
git remote add origin https://github.com/raggle-ai/homebrew-pets.git
git branch -M main
git push -u origin main

📝 Formula Structure ​

Current Formula ​

ruby
# typed: strict
# frozen_string_literal: true

# OpenPets Homebrew Formula
class Openpets < Formula
  desc "AI plugin infrastructure and shared utilities for OpenCode"
  homepage "https://pets.raggle.co"
  url "https://registry.npmjs.org/openpets/-/openpets-1.0.4.tgz"
  sha256 "0000000000000000000000000000000000000000000000000000000000000000"
  license "MIT"

  depends_on "node@20"

  def install
    system "npm", "install", *Language::Node.std_npm_args(libexec)

    (bin/"pets").write_env_script "#{Formula["node@20"].opt_bin}/node",
                                  "#{libexec}/lib/node_modules/openpets/cli.ts",
                                  NODE_PATH: "#{libexec}/lib/node_modules"

    (bin/"pets-mcp").write_env_script "#{Formula["node@20"].opt_bin}/node",
                                      "#{libexec}/lib/node_modules/openpets/mcp-server.ts",
                                      NODE_PATH: "#{libexec}/lib/node_modules"
  end

  test do
    system bin/"pets", "--help"
  end
end

🔄 Updating for New Version ​

After Publishing to NPM ​

Run the checksum updater:

bash
./scripts/update-openpets-checksums.sh

This automatically:

  • Fetches latest version from npm
  • Downloads package
  • Calculates SHA256
  • Updates formula

Manual Update ​

bash
VERSION=1.0.5

# Get SHA256
curl -sL "https://registry.npmjs.org/openpets/-/openpets-${VERSION}.tgz" | shasum -a 256

# Update homebrew-tap/openpets.rb
# 1. Change url to new version
# 2. Update sha256 with calculated value

# Commit and push
cd homebrew-tap
git add openpets.rb
git commit -m "Update to version ${VERSION}"
git push

🧪 Testing Formula ​

Local Testing ​

bash
cd homebrew-tap

# Install from local formula
brew install --build-from-source ./openpets.rb

# Verify installation
pets --version
pets --help
pets-mcp --help

# Run formula test
brew test openpets

# Uninstall
brew uninstall openpets

Validation ​

bash
# Check style
brew style openpets.rb

# Audit formula
brew audit --strict openpets

# Auto-fix style issues
brew style --fix openpets.rb

📦 Formula Components ​

Dependencies ​

ruby
depends_on "node@20"

Requires Node.js 20+ to be installed via Homebrew.

Installation ​

ruby
def install
  # Install npm package to libexec
  system "npm", "install", *Language::Node.std_npm_args(libexec)

  # Create wrapper scripts with NODE_PATH
  (bin/"pets").write_env_script ...
  (bin/"pets-mcp").write_env_script ...
end

What this does:

  1. Installs npm package to isolated libexec directory
  2. Creates wrapper scripts in bin/ that:
    • Point to correct Node.js
    • Set NODE_PATH for module resolution
    • Execute TypeScript files with tsx

Testing ​

ruby
def test
  system bin/"pets", "--help"
end

Verifies the pets command works after installation.

👥 User Installation ​

Add Tap ​

bash
brew tap raggle-ai/pets

Install OpenPets ​

bash
brew install openpets

Verify ​

bash
pets --version
pets list
pets-mcp --help

Upgrade ​

bash
brew upgrade openpets

Uninstall ​

bash
brew uninstall openpets
brew untap raggle-ai/pets

🔍 Troubleshooting ​

Formula Fails to Install ​

Check logs:

bash
brew install --verbose --debug openpets

Common issues:

  • Node.js not found → Install with brew install node@20
  • Network error → Check npm registry accessibility
  • Permission error → Check Homebrew permissions

Wrong Version Installed ​

Clear cache:

bash
brew cleanup openpets
brew uninstall openpets
brew install openpets

Command Not Found ​

Check installation:

bash
brew list openpets
which pets

Fix PATH:

bash
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

🎨 Formula Best Practices ​

Style Guidelines ​

  • ✅ Use typed: strict sigil
  • ✅ Use frozen_string_literal: true
  • ✅ Add descriptive comment before class
  • ✅ Use std_npm_args for npm install
  • ✅ Align multi-line arguments
  • ✅ Include test block

Testing ​

bash
# Run all checks
brew style openpets.rb
brew audit --strict openpets.rb
brew install --build-from-source ./openpets.rb
brew test openpets

🤖 Automation ​

GitHub Actions ​

The main repository includes automation for updating the formula:

.github/workflows/publish-distributions.yml:

yaml
- name: Update Homebrew formula
  uses: mislav/bump-homebrew-formula-action@v3
  with:
    formula-name: openpets
    homebrew-tap: raggle-ai/homebrew-pets
    download-url: https://registry.npmjs.org/openpets/-/openpets-${{ version }}.tgz
  env:
    COMMITTER_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}

Manual Trigger ​

bash
gh workflow run publish-distributions.yml -f version=1.0.5

📊 Formula Info ​

View Formula ​

bash
brew info openpets
brew info raggle-ai/pets/openpets

Check Dependencies ​

bash
brew deps openpets

View Caveats ​

bash
brew info openpets | grep -A20 "^==> Caveats"

🌍 Publishing to Official Homebrew ​

Submit to homebrew-core ​

For wider distribution, submit to official Homebrew:

  1. Prepare formula:

    bash
    brew install --build-from-source ./openpets.rb
brew test openpets
brew audit --strict openpets.rb

  2. Submit PR:

    bash
    # Fork homebrew-core
gh repo fork Homebrew/homebrew-core

# Add formula
cp openpets.rb ~/homebrew-core/Formula/

# Create PR
cd ~/homebrew-core
git checkout -b openpets
git add Formula/openpets.rb
git commit -m "openpets 1.0.4 (new formula)"
gh pr create

  3. Requirements:

    • ✅ Formula passes all audits
    • ✅ Package has 75+ GitHub stars OR 30+ forks
    • ✅ Notable project (20,000+ downloads/month)
    • ✅ Stable release (not beta)
    • ✅ Active maintenance

Note: Start with custom tap, submit to core later as project grows.

📝 Release Checklist ​

When releasing new version:

  • [ ] Publish to npm
  • [ ] Run ./scripts/update-openpets-checksums.sh
  • [ ] Test formula locally
  • [ ] Verify checksums match
  • [ ] Push to tap repository
  • [ ] Test user installation
  • [ ] Update tap README if needed

🆘 Support ​