OpenPets Deployment Documentation

Complete deployment guide for publishing OpenPets across multiple package managers and distribution channels.

📦 Package Naming Strategy

Core Package: openpets (no scope)

The core package is published as openpets without the @ scope for maximum simplicity and ease of installation.

Rationale:

• ✅ Simpler to install: npm install -g openpets vs npm install -g @openpets/core
• ✅ Cleaner CLI name: Package name matches the command pets
• ✅ Better discoverability: Unscoped packages appear first in npm search
• ✅ Familiar pattern: Similar to popular tools like typescript, eslint, prettier
• ✅ Shorter commands: Less typing for users

Pet Packages: @openpets/* (scoped)

Individual pets are published under the @openpets/ scope for organization and namespace management.

Examples:

• @openpets/maps
• @openpets/email
• @openpets/jira
• @openpets/github

Rationale:

• ✅ Organized namespace: All pets grouped under one org
• ✅ Prevents naming conflicts: Protected namespace
• ✅ Professional appearance: Shows project organization
• ✅ Easy filtering: npm search @openpets shows all pets
• ✅ Consistent branding: All pets clearly associated with OpenPets

Comparison

Scenario	Core Package	Pet Packages
Installation	npm install -g openpets	npm install @openpets/maps
Usage	pets --help	Used via core
Purpose	CLI tool & infrastructure	Plugin extensions
Naming	Unscoped (simple)	Scoped (organized)

---

📚 Deployment Guides

By Package Manager

• NPM - Publishing to npm registry
• Homebrew - Creating and maintaining Homebrew tap
• AUR/Paru - Publishing to Arch User Repository
• Curl Install - Shell script installer setup
• Web Installer - Deploying installation page

By Task

• Publishing Guide - Comprehensive publishing documentation
• NPM Packages - npm package management
• Registry - Registry and package distribution
• GitHub Actions Secrets - CI/CD secrets configuration
• Git Hooks - Pre-commit and deployment hooks
• Git Hooks Summary - Quick reference for git hooks

---

🚀 Quick Start

Publishing Core Package

cd src/core
npm publish --access public

Publishing Individual Pets

Use the publish-pet.ts script for consistent, secure publishing:

# From repository root
bun scripts/publish-pet.ts <pet-name>

# Examples
bun scripts/publish-pet.ts maps
bun scripts/publish-pet.ts jira --preview  # Dry-run mode

# The script handles:
# - Workspace dependency resolution
# - Security scanning
# - Auto version bumping
# - File whitelist filtering
# - npmignore generation

Publishing Multiple Pets

# Publish all pets
for pet in maps email jira gitlab slack posthog; do
  bun scripts/publish-pet.ts "$pet"
done

# Update distribution files
./scripts/update-openpets-checksums.sh

🎯 Distribution Status

Method	Package Name	Status	Guide
NPM	openpets	✅ Ready	npm.md
Homebrew	openpets	⏳ Setup needed	homebrew.md
AUR	openpets	⏳ Setup needed	aur.md
Curl	N/A	✅ Ready	curl.md
Web Installer	N/A	✅ Ready	curl.md

---

📋 Pre-Deployment Checklist

Before deploying any version:

• [ ] All tests pass: bun run validate:all
• [ ] Security scan passes: bun scripts/publish-pet.ts <pet> --preview
• [ ] No sensitive files in tarball (test files, .env, credentials)
• [ ] Pets use loadEnv() from openpets (not local dotenv)
• [ ] CHANGELOG.md updated
• [ ] All changes committed
• [ ] Git tag created: git tag v1.0.x

Note: Version bumping is handled automatically by publish-pet.ts if the version already exists on npm.

---

🆘 Need Help?

• Check specific deployment guide for your platform
• See the FAQ for common issues
• Review Testing Guide for validation details

---

📄 Related Documentation

• Publishing Guide - NPM publish details
• Testing Guide - Validation workflow
• Installation Guide - Complete setup guide