Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ on:
branches: [main]
pull_request:
schedule:
- cron: "0 6 * * 1" # weekly: the paseo-main job catches upstream drift
- cron: "0 6 * * 1" # weekly: upstream drift (paseo-main) and new Paseo releases (verified-paseo)
workflow_dispatch:

permissions:
Expand Down Expand Up @@ -96,3 +96,19 @@ jobs:
run: npm ci && npm run build:client && npm run build:plugin
- working-directory: devkit
run: npm ci && npm test

verified-paseo:
name: verified on the latest Paseo release
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- env:
GH_TOKEN: ${{ github.token }}
run: |
latest=$(gh release view --repo getpaseo/paseo --json tagName --jq '.tagName | ltrimstr("v")')
verified=$(sed -n 's/^export const VERIFIED_PASEO = "\(.*\)";$/\1/p' src/compat.ts)
if [ "$latest" != "$verified" ]; then
echo "::error::Paseo $latest is out and ppd is verified on ${verified:-?}: run PPD_E2E=1 npm test and ppd web with Paseo $latest on a Mac, then bump VERIFIED_PASEO in src/compat.ts"
exit 1
fi
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Changelog

## Unreleased

- Verified on Paseo 0.12.0: `ppd daemon up` and `ppd doctor` no longer print the version note on it.

## 0.1.0 (2026-10-18)

First public release. Verified on macOS with Paseo 0.11.4.
Expand Down
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,15 +73,15 @@ $ npx ppd check examples/hello-plugin
PASS manifest hello-plugin, requires paseo >=0.11.2
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 paseo-compile compilePlugin of the Paseo 0.12.0 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
PASS client-eval contributions: addWorkspacePanel, addCommandCenterItem
PASS hermes-class no class syntax in the client bundle
SKIP hermes-parse hermesc not found (install react-native as a devDependency, or set HERMESC)
SKIP hermes-vm Hermes VM not found (react-native ships it for macOS; or set HERMES)
PASS lucide-icons 2 icon name(s) valid against 6354 Lucide icons of the Paseo 0.11.4 app (/Applications/Paseo.app)
PASS lucide-icons 2 icon name(s) valid against 6354 Lucide icons of the Paseo 0.12.0 app (/Applications/Paseo.app)
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

11 passed, 0 warnings, 0 failed, 2 skipped
Expand All @@ -91,7 +91,7 @@ dev daemon "default" up
url: http://127.0.0.1:7800
home: $TMPDIR/ppd-default-aiOmq4
pid: 51399
paseo: 0.11.4
paseo: 0.12.0
workspace created for /tmp/demo-workspace

$ npx ppd install examples/hello-plugin # rerun after edits, or: npx ppd dev examples/hello-plugin
Expand Down Expand Up @@ -245,11 +245,11 @@ Or for one plugin repo: copy the same directory into the repo's `.claude/skills/
- run: npx ppd registry precheck
```

It also has a weekly job that checks out Paseo main, sets `PASEO_SOURCE` and runs `ppd check` with the latest SDK, so upstream changes break your CI before they break your users. This repo's own [CI](.github/workflows/ci.yml) runs typecheck, tests, a CLI smoke test and a package check on Node 22 and 24, builds the docs site, and runs the test suite weekly against Paseo main.
It also has a weekly job that checks out Paseo main, sets `PASEO_SOURCE` and runs `ppd check` with the latest SDK, so upstream changes break your CI before they break your users. This repo's own [CI](.github/workflows/ci.yml) runs typecheck, tests, a CLI smoke test and a package check on Node 22 and 24, builds the docs site, and every week runs the test suite against Paseo main and checks that ppd is verified on the latest Paseo release.

## Compatibility

Verified on macOS with Paseo 0.11.4 (desktop app and CLI). CI runs on Linux without Paseo, where daemon tests skip and `ppd check` runs as an approximation.
Verified on macOS with Paseo 0.12.0 (desktop app and CLI). CI runs on Linux without Paseo, where daemon tests skip and `ppd check` runs as an approximation.

`ppd` relies on parts of Paseo that are not a public API. When one of them moves in a new Paseo release, `ppd` says what it expected instead of blaming your plugin:

Expand All @@ -270,11 +270,11 @@ Verified on macOS with Paseo 0.11.4 (desktop app and CLI). CI runs on Linux with
- Without the Paseo app or `PASEO_SOURCE` (Linux CI) the compile is an approximation and icon names are checked only against the plugin's own `lucide-react-native`, if any.
- Time limits are 30 s per evaluated bundle and 120 s for the real compile, server evaluation included. There is no CLI flag; `runChecks` and `describeHostContract` take `evalTimeoutMs` and `compileTimeoutMs`.
- The 32 MiB relay budget comes from field experience, not from Paseo source; direct connections allow 100 MiB.
- `ppd web` needs Google Chrome or a Playwright Chromium matching `playwright-core`. Its selectors follow the Paseo 0.11 web UI and may need updates when the app changes.
- `ppd web` needs Google Chrome or a Playwright Chromium matching `playwright-core`. Its selectors follow the Paseo 0.12 web UI and may need updates when the app changes.
- No iOS command: the simulator build is manual (see the skill). No multi-touch injection for Android.
- `ppd release` and `ppd registry update` are tested against local Git repos and a stub validator, not yet end to end against GitHub and the live registry.
- The daemon end-to-end tests are opt-in (`PPD_E2E=1 npm test`, `PPD_E2E_PORT` to pin the port) because CI has no Paseo CLI.
- macOS and Linux only. Tested on macOS with Paseo 0.11.4 (see [Compatibility](#compatibility)).
- macOS and Linux only. Tested on macOS with Paseo 0.12.0 (see [Compatibility](#compatibility)).

## Roadmap

Expand Down
4 changes: 2 additions & 2 deletions docs-site/src/routes/(docs)/docs/check/+page.svx
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,10 @@ The panel template with two typical mistakes: an icon name the app's Lucide buil
small `class` in the client.

```text
PASS manifest my-plugin, requires paseo >=0.11.4
PASS manifest my-plugin, requires paseo >=0.12.0
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 paseo-compile compilePlugin of the Paseo 0.12.0 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
Expand Down
3 changes: 2 additions & 1 deletion docs-site/src/routes/(docs)/docs/compatibility/+page.svx
Original file line number Diff line number Diff line change
Expand Up @@ -51,5 +51,6 @@ note: ppd was verified on Paseo <verified>; this is <found>

The devkit's CI runs its test suite every week against a fresh build of Paseo main (`PASEO_SOURCE`), and
[`examples/ci.yml`](https://github.com/nkwib/paseo-plugin-devkit/blob/main/examples/ci.yml) does the same for your
plugin. When something breaks, an issue with the message helps:
plugin. A second weekly job fails once Paseo's latest release is no longer {meta.verifiedPaseo}, until ppd is verified on
the new one. When something breaks, an issue with the message helps:
[nkwib/paseo-plugin-devkit/issues](https://github.com/nkwib/paseo-plugin-devkit/issues).
8 changes: 4 additions & 4 deletions docs-site/src/routes/(docs)/docs/getting-started/+page.svx
Original file line number Diff line number Diff line change
Expand Up @@ -65,18 +65,18 @@ npm run check && npm test
```

```text
PASS manifest my-plugin, requires paseo >=0.11.4
PASS manifest my-plugin, requires paseo >=0.12.0
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 paseo-compile compilePlugin of the Paseo 0.12.0 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
PASS client-eval contributions: addWorkspacePanel, addCommandCenterItem
PASS hermes-class no class syntax in the client bundle
PASS hermes-parse hermesc compiles the client bundle
PASS hermes-vm Hermes VM evaluated the bundle and ran the contribution (addWorkspacePanel, addCommandCenterItem)
PASS lucide-icons 2 icon name(s) valid against 6354 Lucide icons of the Paseo 0.11.4 app (/Applications/Paseo.app)
PASS lucide-icons 2 icon name(s) valid against 6354 Lucide icons of the Paseo 0.12.0 app (/Applications/Paseo.app)
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

13 passed, 0 warnings, 0 failed, 0 skipped
Expand All @@ -96,7 +96,7 @@ dev daemon "default" up
url: http://127.0.0.1:7800
home: $TMPDIR/ppd-default-2kCaQs
pid: 84941
paseo: 0.11.4
paseo: 0.12.0
workspace created for ~/code/my-plugin
```

Expand Down
8 changes: 5 additions & 3 deletions docs-site/src/routes/(docs)/docs/troubleshooting/+page.svx
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
<script>
import PageMeta from '#lib/components/PageMeta.svelte';
import { meta } from '#lib/generated/meta.js';
</script>

<PageMeta
Expand Down Expand Up @@ -58,7 +59,7 @@ build options. That is expected on Linux CI. On a Mac, install Paseo or point `P
<h3 id="layout">could not load Paseo's plugin compiler</h3>

```text
FAIL paseo-compile could not load Paseo's plugin compiler from the Paseo 0.12.0 app (/Applications/Paseo.app): expected ... ppd was verified on Paseo 0.11.4 and found 0.12.0, so this release may lay things out differently. Run `ppd check --approx` for the esbuild replica, or set PASEO_SOURCE to a getpaseo/paseo checkout. Please report it at ...
FAIL paseo-compile could not load Paseo's plugin compiler from the Paseo 0.13.0 app (/Applications/Paseo.app): expected ... ppd was verified on Paseo 0.12.0 and found 0.13.0, so this release may lay things out differently. Run `ppd check --approx` for the esbuild replica, or set PASEO_SOURCE to a getpaseo/paseo checkout. Please report it at ...
```

ppd reads the compiler, the evaluator and the Lucide list from inside the installed app, which is not a public API.
Expand Down Expand Up @@ -156,11 +157,12 @@ runs in several directories leave several.
<h3 id="web-labels">The web UI did not show ...</h3>

```text
the Paseo web UI did not show the workspace (a "Workspace actions" button) within 30 s. ppd finds it by the labels of the Paseo 0.11.4 web UI; a different version may have renamed it ...
the Paseo web UI did not show the workspace (a "Workspace actions" button) within 30 s. ppd finds it by the labels of the Paseo 0.12.0 web UI; a different version may have renamed it ...
```

`ppd web` finds the app shell, workspaces and the Command Center by their accessible names. On a Paseo other than
0.11.4 a renamed label ends here; please report it. On 0.11.4, retry with `--headed` to watch what the page does.
{meta.verifiedPaseo} a renamed label ends here; please report it. On {meta.verifiedPaseo}, retry with `--headed` to
watch what the page does.

<h2 id="fake-agent">Fake agent</h2>

Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/routes/+page.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ dev daemon "default" up
url: http://127.0.0.1:7800
home: $TMPDIR/ppd-default-2kCaQs
pid: 84941
paseo: 0.11.4
paseo: 0.12.0
workspace created for ~/code/my-plugin
<span class="prompt">$</span> npx ppd check | tail -1
<span class="good">13 passed, 0 warnings, 0 failed, 0 skipped</span>
Expand Down
2 changes: 1 addition & 1 deletion skills/paseo-plugin-dev/references/host-contract.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Paseo plugin host contract

What Paseo 0.11 actually gives a plugin at runtime. `ppd check` tests the rows marked (checked).
What Paseo 0.11 and 0.12 actually give a plugin at runtime. `ppd check` tests the rows marked (checked).

| Area | Contract | What to do |
| --- | --- | --- |
Expand Down
2 changes: 1 addition & 1 deletion src/compat.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
// verified on one Paseo release; a different release may move things.

/** The Paseo release whose app layout, daemon flags and web UI labels ppd was verified on. */
export const VERIFIED_PASEO = "0.11.4";
export const VERIFIED_PASEO = "0.12.0";

export const ISSUES_URL = "https://github.com/nkwib/paseo-plugin-devkit/issues";

Expand Down
16 changes: 8 additions & 8 deletions test/compat.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ function fakeApp(version: string): Extract<PaseoHost, { kind: "app" }> {

describe("layout mismatch messages", () => {
it("name what was expected, the verified and found versions, and where to report", () => {
const message = layoutMismatch("could not do X", "a file at Y", "0.12.0", "Use Z");
const message = layoutMismatch("could not do X", "a file at Y", "0.13.0", "Use Z");
expect(message).toContain("could not do X: expected a file at Y.");
expect(message).toContain(`verified on Paseo ${VERIFIED_PASEO} and found 0.12.0`);
expect(message).toContain(`verified on Paseo ${VERIFIED_PASEO} and found 0.13.0`);
expect(message).toContain("Use Z.");
expect(message).toContain(ISSUES_URL);
expect(layoutMismatch("p", "e", VERIFIED_PASEO, "n")).toContain("the install may be incomplete");
Expand All @@ -30,20 +30,20 @@ describe("layout mismatch messages", () => {
it("flag a Paseo version other than the verified one", () => {
expect(versionNote(VERIFIED_PASEO)).toBeNull();
expect(versionNote(null)).toBeNull();
expect(versionNote("0.12.0")).toBe(`ppd was verified on Paseo ${VERIFIED_PASEO}; this is 0.12.0`);
expect(versionNote("0.13.0")).toBe(`ppd was verified on Paseo ${VERIFIED_PASEO}; this is 0.13.0`);
expect(versionNote("paseo 0.13.1-beta.2\n")).toContain("this is 0.13.1-beta.2");
});
});

describe("an app whose bundle layout differs", () => {
it("fails the real compile as a host problem with the way around it", async () => {
const result = await compileWithHost(EXAMPLE, fakeApp("0.12.0"), 30_000);
const result = await compileWithHost(EXAMPLE, fakeApp("0.13.0"), 30_000);
expect(result.stage).toBe("load");
const [first, ...rest] = result.error!.split("\n");
expect(first).toContain("could not load Paseo's plugin compiler from the Paseo 0.12.0 app");
expect(first).toContain("could not load Paseo's plugin compiler from the Paseo 0.13.0 app");
expect(first).toContain(APP_PLUGINS);
expect(first).toContain("ppd check --approx");
expect(first).toContain(`verified on Paseo ${VERIFIED_PASEO} and found 0.12.0`);
expect(first).toContain(`verified on Paseo ${VERIFIED_PASEO} and found 0.13.0`);
expect(rest.join("\n")).toMatch(/Cannot find module|ERR_MODULE_NOT_FOUND/);
});

Expand All @@ -60,9 +60,9 @@ describe("an app whose bundle layout differs", () => {
});

it("says why the app's icon list is not used", () => {
const host = fakeApp("0.12.0");
const host = fakeApp("0.13.0");
const missing = iconListProblem(host, null)!;
expect(missing).toContain("could not read the Lucide icon list of the Paseo 0.12.0 app");
expect(missing).toContain("could not read the Lucide icon list of the Paseo 0.13.0 app");
expect(missing).toContain("Icon names are not checked");
expect(iconListProblem(host, { exact: false })).toContain("plugin's own lucide-react-native instead");
expect(iconListProblem(host, { exact: true })).toBeNull();
Expand Down
2 changes: 2 additions & 0 deletions vitest.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,7 @@ export default defineConfig({
test: {
include: ["test/**/*.test.ts"],
testTimeout: 60_000,
// The daemon end-to-end files take ports from the same range (or the same PPD_E2E_PORT), so one file at a time.
fileParallelism: process.env.PPD_E2E !== "1",
},
});
Loading