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

• npm
• GitHub
• pi.dev

License

MIT