pi-pkg-guard

Guards against unregistered pi packages — installed via npm but not registered in pi's settings.

Quick Start

pi install npm:pi-pkg-guard

Then in pi: /package-guard

The Problem

npm install -g pi-token-burden  # Installs to npm global
# But pi doesn't know about it!

pi-pkg-guard detects, warns, and fixes this automatically.

An unregistered package is a pi extension installed via npm but not registered in pi's settings. This creates a mismatch where the package exists on your system, but pi can't use it.

Features

• Startup check — Warns if unregistered packages found (debounced to once/hour)
• npm guard — Warns when you run npm install -g pi-*
• Scan & Sync — Find and register unregistered packages automatically
• Backup — Save to local file + optional GitHub Gist (with versioned schema)
• Restore — Selectively restore packages from backup with automatic legacy migration
• Schema Validation — Strict backup validation with $schema field for future-proofing
• Multi-language — English, Spanish, and more (ICU MessageFormat)

Documentation

📚 View Documentation — Complete documentation index

Quick Links:

• Getting Started — First time tutorial
• Installation — Install options
• Usage Guide — Complete feature guide
• Backup Strategies — Best practices for backups
• Multi-Machine Setup — Sync across devices
• Troubleshooting — Common issues & solutions

Reference:

• Architecture — Technical design
• API — Extension API
• Security Model — Security validations
• i18n Guide — Translation contributor guide

Development:

• Contributing — Contributor guidelines
• Testing — Test writing guide
• Release Process — Release workflow

Passive Warnings

Startup: 3 unregistered pi package(s). Run /package-guard

npm install: Use 'pi install npm:pi-foo' instead of 'npm install -g'

Development

git clone https://github.com/alexleekt/pi-pkg-guard.git
cd pi-pkg-guard
npm install

just test      # Run tests
just check     # Run all checks
just release   # Create release

See Contributing Guide for details.

Release Process

This project uses GitHub Actions with Trusted Publishing (OIDC) for automated npm releases:

just release        # Auto-detects version from package.json

See full details in Release Process.

License

MIT © Alex Lee