@alexleekt/pi-pkg-guard

Don't let orphaned packages clutter your agent.

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

Quick Start

pi install npm:@alexleekt/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
• npm guard — Warns when you run npm install -g pi-*
• Scan & Register — 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

Quick Commands

| Command | Action | |---------|--------| | /package-guard | Open interactive menu | | /package-guard scan | Scan and fix unregistered packages | | /package-guard backup | Save backup (local + Gist) | | /package-guard restore | Restore packages from backup | | /package-guard config | Open configuration settings |

In-Menu Navigation

Menu items are numbered for quick selection:

| # | Option | |---|--------| | 1 | Scan / Register | | 2 | Backup | | 3 | Restore | | 4 | Config | | 5 | Exit |

Passive Warnings

Startup: 3 packages to register. Run /package-guard

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

Development

git clone https://github.com/alexleekt/pi-extensions.git
cd packages/pi-pkg-guard
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