Host-contract checks

Paseo's plugin host accepts less than its types suggest. An unknown icon name drops your whole client with one console warning; class syntax works on web and crashes on phones; a module the host does not provide throws only when the plugin loads. ppd check finds these before you install.

npx ppd check            # the plugin in cwd
npx ppd check path/to/plugin --json

It exits 1 on any FAIL; warnings and skips do not fail. All flags are on Commands.

Where the compiler comes from

ppd check compiles and evaluates with Paseo's own code when it can find it, in this order:

1. --paseo-source or PASEO_SOURCE: a getpaseo/paseo checkout with npm ci done, to test against unreleased Paseo.
2. The installed Paseo app: --paseo-app, PASEO_APP, the app behind paseo on PATH, /Applications/Paseo.app, ~/Applications/Paseo.app. The compiler and evaluator are read from its app.asar, the Lucide icon list from its web bundle (app-dist).
3. Neither: an esbuild replica with Paseo 0.11's build options and rules vendored from Paseo. The output says APPROXIMATION on the paseo-compile line and reports the replica's compile as approx-compile. --approx forces this path, which is what CI without Paseo sees.

The checks

react-native as a devDependency ships both hermesc and the Hermes VM (ppd create adds it); HERMESC and HERMES point at other binaries.

A failing run

The panel template with two typical mistakes: an icon name the app's Lucide build does not have (HandWaving) and a small class in the client.

PASS  manifest         my-plugin, requires paseo >=0.11.4
PASS  imports          client, server and shared boundaries hold
PASS  dependencies     no runtime packages
PASS  paseo-compile    compilePlugin of the Paseo 0.11.4 app (/Applications/Paseo.app) accepted the plugin
PASS  client-requires  client requires only host modules (@getpaseo/plugin, @getpaseo/plugin/client, react, react-native, react/jsx-runtime, zod)
PASS  server-requires  server requires only host modules and Node built-ins
PASS  server-eval      Paseo's evaluator ran the contribution in 0 ms; RPCs: hello.greet
FAIL  client-eval      the app would reject this plugin client and show none of its UI
      Unknown Lucide icon: HandWaving
      contributions: addWorkspacePanel, addCommandCenterItem
FAIL  hermes-class     client bundle contains class syntax, which crashes plugin loading on Hermes (getpaseo/paseo#5783)
      Transforming class syntax to the configured target environment is not supported yet (line 95): var Greeting = class {
FAIL  hermes-parse     hermesc rejected the client bundle
      $TMPDIR/ppd-hermes-0UWV2R/bundle.js:95:16: error: Invalid expression encountered
      var Greeting = class {
                     ^~~~~~~
      Emitted 1 errors. exiting.
FAIL  hermes-vm        Hermes VM failed at evaluate: SyntaxError: 95:16:Invalid expression encountered
FAIL  lucide-icons     unknown Lucide names in contributions (Paseo throws at registration): HandWaving
PASS  bundle-size      client 5 KiB (2 KiB gzip), budget 2.0 MiB; server 2 KiB (1 KiB gzip), eval 0 ms, budget 32.0 MiB

8 passed, 0 warnings, 5 failed, 0 skipped

Paseo itself compiled this plugin without complaint, and on the web the panel would simply not be there. Installing it shows the same verdict from the other side: client-rejected.

In your test suite

// test/host-contract.test.ts: one vitest test per check
import { fileURLToPath } from "node:url";
import { describeHostContract } from "paseo-plugin-devkit/vitest";

describeHostContract(fileURLToPath(new URL("..", import.meta.url)));

Skipped checks show up as skipped tests. Warnings pass unless you pass allowWarnings: false; the other options are the same as ppd check's (paseoApp, paseoSource, maxClientBytes, maxServerBytes).

RPC handlers time out after 30 s in the host, and responses behind the relay share a 32 MiB frame. To keep a handler well inside both:

import { assertWithinRpcBudget } from "paseo-plugin-devkit/testing";

await assertWithinRpcBudget(() => handlers.get("doc.render")!(worstCaseInput)); // < 15 s, < 8 MiB

In CI

Linux runners have no Paseo app, so ppd check runs the approximation there: imports, evaluation, Hermes and sizes still run, the compile is the esbuild replica, and icon names are checked against the plugin's own lucide-react-native if it has one. examples/ci.yml adds a weekly job that checks out Paseo main, sets PASEO_SOURCE and runs the real compiler with the latest SDK.