Pets

Appearance

NPM Deployment Guide ​

Publishing OpenPets packages to the npm registry.

📦 Packages ​

Core Package ​

Name: openpetsLocation: src/core/Version: 1.0.4

Published without @ scope for simplicity.

Pet Packages ​

Scope: @openpets/Location: pets/*/

Published with scope for organization.

Examples:

  • @openpets/maps (v1.0.7)
  • @openpets/email (v1.0.1)
  • @openpets/jira
  • @openpets/github

🔒 Security Best Practices ​

2-Factor Authentication (2FA) ​

  • Maintainers: Must have 2FA enabled on their npm accounts.
  • Automation: Use Granular Access Tokens with "Publish" permissions restricted to the @openpets scope and specific IP ranges if possible. Avoid using legacy tokens.

Namespace Protection ​

Using the @openpets scope prevents "typo-squatting" attacks where malicious actors publish packages with similar names (e.g., openpets-mps vs @openpets/maps). Ensure all new plugins are added to the organization scope.

Pre-Flight Checks ​

The publishing scripts include automated security checks:

  • Secret Scanning: Scans src/ for potential API keys or .env files before publishing.
  • Dependency Pinning: Workspace dependencies are resolved to specific versions to prevent supply chain drift.
  • File Whitelist: Only explicitly listed files are included (index.ts, src/, commands.json, etc.).
  • npmignore Template: Auto-generated .npmignore excludes test files, backups, debug scripts, and sensitive files.

Environment Variable Handling ​

Pets use the standardized loadEnv() function from the openpets core package:

typescript
import { loadEnv } from "openpets"

export const MyPlugin = async () => {
  const env = loadEnv("my-plugin")
  const API_KEY = env.MY_API_KEY
  // ...
}

How loadEnv works:

  1. Loads from .env file in the project's working directory (not the package cache)
  2. Loads from .pets/config.json if it exists (pet-specific config)
  3. Returns only project-relevant environment variables

This ensures pets never load .env from their installed cache location, and credentials are never bundled with published packages.

🚀 Publishing ​

Prerequisites ​

  1. Login to npm:

    bash
    npm login
npm whoami  # Should show: raggle_npm

  2. Verify organization access: Visit: https://www.npmjs.com/settings/openpets/packages

Publish Core Package ​

bash
cd src/core
npm publish --access public

Result:

+ openpets@1.0.4

Publish Individual Pet ​

Use the publish-pet.ts script which handles workspace dependencies, security checks, and version management:

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

# Examples
bun scripts/publish-pet.ts maps
bun scripts/publish-pet.ts jira
bun scripts/publish-pet.ts gitlab

# Preview mode (dry-run)
bun scripts/publish-pet.ts maps --preview

# Publish to specific channel
bun scripts/publish-pet.ts maps --channel beta

What the publish script does:

  1. Ensures .npmignore exists with secure defaults
  2. Runs security scan for secrets/credentials
  3. Replaces workspace:* dependencies with actual versions
  4. Auto-bumps version if already published
  5. Applies whitelist file filter (only includes core files)
  6. Verifies tarball contents before publishing
  7. Publishes to npm registry

Result:

+ @openpets/maps@1.0.8

Publish All Pets ​

bash
# From repository root
npm run publish:pets

Or manually with the script:

bash
for pet in maps email jira gitlab slack; do
  bun scripts/publish-pet.ts "$pet"
done

🧪 Testing Before Publish ​

Dry Run ​

Test without actually publishing:

bash
# Core
cd src/core
npm publish --dry-run --access public

# Pets
cd pets/maps
npm publish --dry-run --access public

Pack and Inspect ​

Create a tarball to inspect what will be published:

bash
npm pack
tar -tzf openpets-1.0.4.tgz

⚙️ Configuration ​

package.json Settings ​

Core package (src/core/package.json):

json
{
  "name": "openpets",
  "version": "1.0.4",
  "publishConfig": {
    "access": "public"
  },
  "bin": {
    "pets": "./cli.ts",
    "pets-mcp": "./mcp-server.ts"
  },
  "files": [
    "*.ts",
    "*.js",
    "*.d.ts",
    "ai-client-base/**/*",
    "!**/*.test.ts"
  ]
}

Pet package (pets/maps/package.json):

json
{
  "name": "@openpets/maps",
  "version": "1.0.7",
  "publishConfig": {
    "access": "public"
  }
}

Note: The files array is preserved if already present, or dynamically added by publish-pet.ts during publishing to ensure a consistent whitelist approach:

json
{
  "files": [
    "index.ts",
    "index.js",
    "client.ts",
    "client.js",
    "*.d.ts",
    "lib/**/*",
    "src/**/*",
    "commands.json",
    "public/**/*",
    "prompts/**/*",
    "README.md"
  ]
}

This whitelist approach ensures only core plugin files are published, automatically excluding test files, backups, and debug scripts.

📋 Files Included ​

Core Package ​

openpets@1.0.4
├── cli.ts (pets command)
├── mcp-server.ts (pets-mcp command)
├── index.ts
├── build-pet.ts
├── validate-pet.ts
├── logger.ts
├── ai-client-base/
└── ... (23 files total)

Pet Package ​

@openpets/maps@1.0.7
├── index.ts
├── commands.json
├── opencode.json
├── src/
│   └── providers/
│       ├── google-maps.ts
│       ├── mapbox.ts
│       └── openstreetmap.ts
└── ... (8 files total)

🔄 Version Management ​

Bump Version ​

bash
# From package directory
npm version patch  # 1.0.4 -> 1.0.5
npm version minor  # 1.0.4 -> 1.1.0
npm version major  # 1.0.4 -> 2.0.0

Using Bump Script ​

bash
# From repository root
npm run bump

📊 After Publishing ​

Verify Publication ​

bash
# Check core package
npm view openpets

# Check pet package
npm view @openpets/maps

# Check all versions
npm view openpets versions
npm view @openpets/maps versions

Test Installation ​

bash
# Global install
npm install -g openpets
pets --version

# Local install
npm install @openpets/maps

Update Distribution Files ​

After publishing to npm, update other distribution methods:

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

This updates:

  • Homebrew formula checksums
  • PKGBUILD checksums
  • Distribution templates

🏷️ NPM Tags ​

Latest (Default) ​

bash
npm publish --access public
# Published with tag: latest

Beta Release ​

bash
npm publish --access public --tag beta

Users install with:

bash
npm install openpets@beta
npm install @openpets/maps@beta

Alpha Release ​

bash
npm publish --access public --tag alpha

🔐 Access Control ​

All packages use:

json
{
  "publishConfig": {
    "access": "public"
  }
}

This ensures packages are publicly accessible despite being in an organization.

⚠️ Common Issues ​

"Package already exists" ​

Problem: Version already published

Solution:

bash
npm version patch
npm publish --access public

"403 Forbidden" ​

Problem: Not logged in or wrong credentials

Solution:

bash
npm logout
npm login
npm whoami  # Verify: raggle_npm

"Invalid package name" ​

Problem: Name has invalid characters (slashes without scope)

Solution: Use proper format:

  • ❌ openpets/maps
  • ✅ @openpets/maps

"ENEEDAUTH" ​

Problem: Authentication token expired

Solution:

bash
npm login

📈 NPM Stats ​

View Package Info ​

bash
npm info openpets
npm info @openpets/maps

Download Stats ​

Visit:

Or use npm-stat:

bash
npx npm-stat openpets
npx npm-stat @openpets/maps

🔄 Deprecate a Version ​

bash
npm deprecate openpets@1.0.3 "Please upgrade to 1.0.4"
npm deprecate @openpets/maps@1.0.6 "Use 1.0.7 instead"

🗑️ Unpublish (Use Carefully!) ​

Warning: Can only unpublish within 72 hours, and it affects all users.

bash
# Unpublish specific version
npm unpublish openpets@1.0.4

# Unpublish entire package (dangerous!)
npm unpublish openpets --force

Better alternative: Use deprecate instead.

🔐 Security ​

Pre-Publish Security Scan ​

Always run security scan before publishing:

bash
# Run security check (fails on critical issues)
npm run security:check

# Or scan with verbose output
npm run security:scan:verbose

# Scan specific pet
bun scripts/security-scan.ts --dir pets/maps

The security scanner automatically detects:

  • Sensitive files (.env, private keys, credentials)
  • API keys (Google, OpenAI, GitHub, AWS, Stripe)
  • Hardcoded passwords
  • Database connection strings with credentials

Publishing will fail if critical issues are detected.

NPM Account Security ​

Enable 2FA (Required):

bash
npm profile enable-2fa auth-and-writes

Create Granular Access Token:

bash
npm token create \
  --scope=@openpets \
  --description="GitHub Actions Publisher" \
  --expires=365d

See: Security Guide for comprehensive security documentation.

📝 Publishing Checklist ​

Before publishing:

  • [ ] Preview mode passes: bun scripts/publish-pet.ts <pet> --preview
  • [ ] Tests pass: npm test
  • [ ] Pet uses loadEnv() from openpets (not local dotenv)
  • [ ] CHANGELOG.md updated
  • [ ] All changes committed
  • [ ] No .env files in package
  • [ ] No hardcoded API keys
  • [ ] No test files in tarball
  • [ ] 2FA enabled on npm account
  • [ ] Using granular access tokens (not classic)

After publishing:

  • [ ] Verify on npmjs.com
  • [ ] Test installation: npm install -g openpets
  • [ ] Update distribution checksums
  • [ ] Create git tag
  • [ ] Update documentation
  • [ ] Announce release

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

🛡️ npmignore Management ​

The ensure-npmignore.ts script maintains consistent .npmignore files across all pets:

bash
# Ensure all pets have .npmignore
bun scripts/ensure-npmignore.ts --all

# Overwrite existing .npmignore files
bun scripts/ensure-npmignore.ts --all --force

# Single pet
bun scripts/ensure-npmignore.ts pets/maps

Default npmignore template excludes:

  • Sensitive files: .env, *.pem, *.key, credentials*.json
  • Test files: test*.ts, *.test.ts, *.spec.ts
  • Debug files: debug-*.ts, diagnose-*.ts
  • Backup files: *-backup.ts, *.bak
  • Build artifacts: tsconfig.tsbuildinfo, *.log

🆘 Support ​