@realvendex/pi-compat

Pi-native version compatibility checker for pi.dev extensions — detects which pi APIs an extension uses, validates against known version constraints, warns about deprecated/removed APIs, and suggests migration paths.

Packages

Package details

extension

Install @realvendex/pi-compat from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@realvendex/pi-compat
Package
@realvendex/pi-compat
Version
1.0.0
Published
Jun 26, 2026
Downloads
not available
Author
realvendex
License
MIT
Types
extension
Size
99.6 KB
Dependencies
0 dependencies · 5 peers

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-compat

Pi-native version compatibility checker for pi.dev extensions — detect which pi APIs you use, check version support, and get migration suggestions.

Installation

pi install npm:@realvendex/pi-compat

What It Does

pi-compat analyzes your extension's TypeScript source code to detect pi.dev API usage patterns, then checks them against a versioned API catalog to tell you:

  • Which pi versions your extension supports (compatibility matrix)
  • Which APIs you're using that are deprecated (with replacement suggestions)
  • What migration changes are needed to target a specific pi version

It fills the version compatibility gap in the pi.dev QA toolchain:

  • pi-lint → checks API anti-patterns
  • pi-extension-toolkit → checks structure/scaffolding
  • pi-test-harness → runs runtime tests
  • pi-compat → checks version compatibility ← this package

Tools

compat_check

Analyze extension source for pi API usage and validate against known version constraints. Returns a compatibility matrix.

Parameters:

  • source (string, required) — TypeScript source code to analyze
  • targetVersion (string, optional) — Specific pi version to check against (e.g. '1.2.0'). If omitted, checks all known versions.

Example:

Use the compat_check tool with source="<your TypeScript code>"

compat_report

Generate a detailed compatibility report with deprecated API usage, version matrix, and migration suggestions.

Parameters:

  • source (string, required) — TypeScript source code to analyze
  • targetVersion (string, optional) — Target pi version. Defaults to latest.
  • includeCatalog (boolean, optional) — Include the full API catalog reference. Default: false.

Example:

Use the compat_report tool with source="<your TypeScript code>" includeCatalog=true

compat_migrate

Auto-suggest migration changes for deprecated or removed APIs between two pi versions.

Parameters:

  • source (string, required) — TypeScript source code to analyze
  • fromVersion (string, optional) — Current pi version. Defaults to detected minimum.
  • toVersion (string, required) — Target pi version to migrate to.

Example:

Use the compat_migrate tool with source="<your TypeScript code>" toVersion="1.4.0"

API Catalog

pi-compat maintains a versioned catalog of pi.dev APIs covering:

  • Core APIs: registerTool, registerCommand, ExtensionAPI
  • Schema: Type.Object, Type.String, Type.Boolean, Type.Array, Type.Optional, Type.Union, Type.Enum
  • Return patterns: content_text_return, details_field, string_return (deprecated)
  • UI/Context: ctx.hasUI, ctx.workspace, ctx.env, onUpdate
  • Imports: All @earendil-works/* peer deps, typebox, deprecated @mariozechner/*

Versions tracked: 1.0.0 through 1.4.0

How It Works

  1. Static analysis — regex-based scanning of TypeScript source for pi API patterns
  2. Catalog lookup — each detected API is checked against the versioned catalog
  3. Matrix generation — builds a compatibility matrix across all known pi versions
  4. Migration engine — maps deprecated/removed APIs to their replacements

Integration

Fits into the existing pi.dev QA pipeline:

pi-commit-lint → pi-changelog → pi-lint → pi-compat → pi-release

Resources

License

MIT