Pets

Appearance

AUR/Paru Deployment Guide ​

Publishing OpenPets to the Arch User Repository (AUR) for Arch Linux users.

📦 Package Information ​

Package Name: openpetsPKGBUILD Location: distribution-templates/PKGBUILDAUR URL: https://aur.archlinux.org/packages/openpets

Installation Commands:

bash
paru -S openpets
# or
yay -S openpets

🚀 Initial Setup ​

Prerequisites ​

  1. AUR Account

  2. SSH Key Setup

    bash
    # Generate SSH key
ssh-keygen -t ed25519 -C "aur@yourname.com" -f ~/.ssh/aur

# Add to AUR account
cat ~/.ssh/aur.pub
# Paste at: https://aur.archlinux.org/account/

  3. Clone AUR Repository

    bash
    git clone ssh://aur@aur.archlinux.org/openpets.git

📝 PKGBUILD Structure ​

Current PKGBUILD ​

bash
# Maintainer: Raggle <support@raggle.co>

pkgname=openpets
pkgver=1.0.4
pkgrel=1
pkgdesc="AI plugin infrastructure and shared utilities for OpenCode"
arch=('any')
url="https://pets.raggle.co"
license=('MIT')
depends=('nodejs>=18' 'npm')
optdepends=(
    'tsx: TypeScript execution support'
    'opencode: OpenCode AI coding assistant'
)
source=("https://registry.npmjs.org/$pkgname/-/$pkgname-$pkgver.tgz")
sha256sums=('PLACEHOLDER_CHECKSUM')
noextract=("$pkgname-$pkgver.tgz")

package() {
    npm install -g \
        --prefix="$pkgdir/usr" \
        --cache "$srcdir/npm-cache" \
        "$pkgname@$pkgver"

    find "$pkgdir/usr" -type d -name '.cache' -exec rm -r {} +
    find "$pkgdir/usr" -type f -name 'package.json' \
        -execdir sed -i '/_where/d' {} +

    find "$pkgdir/usr" -type d -exec chmod 755 {} +
    find "$pkgdir/usr" -type f -exec chmod 644 {} +

    chmod 755 "$pkgdir/usr/bin/pets"
    chmod 755 "$pkgdir/usr/bin/pets-mcp"

    install -Dm644 \
        "$pkgdir/usr/lib/node_modules/$pkgname/README.md" \
        "$pkgdir/usr/share/doc/$pkgname/README.md"

    if [ -f "$pkgdir/usr/lib/node_modules/$pkgname/LICENSE" ]; then
        install -Dm644 \
            "$pkgdir/usr/lib/node_modules/$pkgname/LICENSE" \
            "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
    fi
}

🔄 Publishing to AUR ​

1. Update PKGBUILD ​

After publishing to npm:

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

This updates:

  • pkgver
  • sha256sums
  • Generates .SRCINFO

2. Copy to AUR Repository ​

bash
cp distribution-templates/PKGBUILD openpets-aur/
cp distribution-templates/.SRCINFO openpets-aur/

3. Commit and Push ​

bash
cd openpets-aur

git add PKGBUILD .SRCINFO
git commit -m "Update to version 1.0.4"

# Push to AUR
GIT_SSH_COMMAND="ssh -i ~/.ssh/aur" git push origin master

🧪 Testing PKGBUILD ​

Build Locally ​

bash
# Copy PKGBUILD to test directory
mkdir -p /tmp/test-openpets
cp distribution-templates/PKGBUILD /tmp/test-openpets/
cd /tmp/test-openpets

# Build package
makepkg -si

# Test installation
pets --version
pets --help

# Cleanup
sudo pacman -R openpets
cd /tmp && rm -rf test-openpets

Validate PKGBUILD ​

bash
# Check syntax
bash -n PKGBUILD

# Lint with namcap
namcap PKGBUILD

# Check built package
makepkg -f
namcap openpets-1.0.4-1-any.pkg.tar.zst

📦 PKGBUILD Components ​

Metadata ​

bash
pkgname=openpets          # Package name
pkgver=1.0.4              # Version (auto-updated)
pkgrel=1                  # Release number (bump for PKGBUILD changes)
pkgdesc="..."             # Short description
arch=('any')              # Architecture-independent
url="https://pets.raggle.co" # Homepage
license=('MIT')           # License

Dependencies ​

bash
depends=('nodejs>=18' 'npm')  # Required
optdepends=(                  # Optional
    'tsx: TypeScript execution support'
    'opencode: OpenCode AI coding assistant'
)

Source ​

bash
source=("https://registry.npmjs.org/$pkgname/-/$pkgname-$pkgver.tgz")
sha256sums=('...')  # Checksum for verification
noextract=("...")   # Don't auto-extract

Package Function ​

bash
package() {
    # Install via npm
    npm install -g --prefix="$pkgdir/usr" ...

    # Cleanup
    find ... -name '.cache' -exec rm -r {} +

    # Fix permissions
    find ... -type d -exec chmod 755 {} +
    find ... -type f -exec chmod 644 {} +
    chmod 755 "$pkgdir/usr/bin/pets"

    # Install docs/license
    install -Dm644 README.md ...
}

👥 User Installation ​

Using AUR Helper (Paru) ​

bash
paru -S openpets

Using AUR Helper (Yay) ​

bash
yay -S openpets

Manual Installation ​

bash
# Clone AUR package
git clone https://aur.archlinux.org/openpets.git
cd openpets

# Build and install
makepkg -si

Upgrade ​

bash
paru -Syu openpets
# or
yay -Syu openpets

Uninstall ​

bash
sudo pacman -R openpets

🔄 Updating Package ​

When New Version Released ​

bash
# 1. Update checksums
./scripts/update-openpets-checksums.sh

# 2. Copy to AUR repo
cp distribution-templates/{PKGBUILD,.SRCINFO} openpets-aur/

# 3. Test build
cd openpets-aur
makepkg -f

# 4. Commit and push
git add PKGBUILD .SRCINFO
git commit -m "Update to version 1.0.5"
GIT_SSH_COMMAND="ssh -i ~/.ssh/aur" git push

When Fixing PKGBUILD ​

If only changing PKGBUILD (no version change):

bash
# Bump pkgrel
pkgrel=2  # was 1

# Regenerate .SRCINFO
makepkg --printsrcinfo > .SRCINFO

# Commit and push
git add PKGBUILD .SRCINFO
git commit -m "Fix PKGBUILD: [description]"
git push

🎨 AUR Best Practices ​

Naming ​

  • ✅ Use simple lowercase name: openpets
  • ✅ Match upstream package name
  • ❌ Don't add unnecessary suffixes

PKGBUILD Quality ​

bash
# Validate
namcap PKGBUILD
namcap *.pkg.tar.zst

# Common checks
- Dependencies complete and minimal
- Correct permissions
- Documentation installed
- No unnecessary files
- Checksum matches

.SRCINFO ​

Always regenerate after PKGBUILD changes:

bash
makepkg --printsrcinfo > .SRCINFO

Never edit .SRCINFO directly!

🤖 Automation ​

Auto-Update Script ​

bash
#!/bin/bash
# scripts/update-aur.sh

set -e

VERSION=$(npm view openpets version)
TARBALL_URL="https://registry.npmjs.org/openpets/-/openpets-$VERSION.tgz"
SHA256=$(curl -sL "$TARBALL_URL" | sha256sum | cut -d' ' -f1)

cd openpets-aur

# Update PKGBUILD
sed -i "s/pkgver=.*/pkgver=$VERSION/" PKGBUILD
sed -i "s/sha256sums=.*/sha256sums=('$SHA256')/" PKGBUILD
sed -i "s/pkgrel=.*/pkgrel=1/" PKGBUILD

# Generate .SRCINFO
makepkg --printsrcinfo > .SRCINFO

# Commit and push
git add PKGBUILD .SRCINFO
git commit -m "Update to version $VERSION"
GIT_SSH_COMMAND="ssh -i ~/.ssh/aur" git push

echo "✓ AUR package updated to $VERSION"

GitHub Actions ​

Include in .github/workflows/publish-distributions.yml:

yaml
- name: Update AUR
  run: |
    eval $(ssh-agent -s)
    ssh-add - <<< "${{ secrets.AUR_SSH_KEY }}"

    git clone ssh://aur@aur.archlinux.org/openpets.git aur-repo
    cp distribution-templates/PKGBUILD aur-repo/
    cp distribution-templates/.SRCINFO aur-repo/

    cd aur-repo
    git config user.name "Raggle Bot"
    git config user.email "bot@raggle.co"
    git add PKGBUILD .SRCINFO
    git commit -m "Update to version ${{ steps.version.outputs.VERSION }}"
    git push

🔍 Troubleshooting ​

Build Fails ​

Check logs:

bash
makepkg -f 2>&1 | tee build.log

Common issues:

  • Missing dependencies → Add to depends=()
  • Network error → Check npm registry
  • Permission error → Fix in package() function

Can't Push to AUR ​

Check SSH:

bash
ssh -i ~/.ssh/aur aur@aur.archlinux.org

Should see: "Hi [username]! You've successfully authenticated..."

Package Marked Out-of-Date ​

Someone flagged it as outdated. Update and push:

bash
# Update to latest version
./scripts/update-aur.sh

# Users will see update available

📊 Package Info ​

View Package on AUR ​

Visit: https://aur.archlinux.org/packages/openpets

Check Package Status ​

bash
# Query installed package
pacman -Qi openpets

# List files
pacman -Ql openpets

# Check orphans
pacman -Qdt

Vote Statistics ​

Users can vote for packages on AUR. More votes = more visibility.

Encourage users to vote:

bash
# In AUR web interface:
# "Vote for this package"

📝 Release Checklist ​

When releasing new version:

  • [ ] Publish to npm
  • [ ] Run ./scripts/update-openpets-checksums.sh
  • [ ] Test PKGBUILD locally: makepkg -si
  • [ ] Verify package works: pets --version
  • [ ] Copy to AUR repo
  • [ ] Commit and push to AUR
  • [ ] Verify on aur.archlinux.org
  • [ ] Test user installation: paru -S openpets

🆘 Support ​