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
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# Changelog

## 0.3.0 (unreleased)

- Add `PaseoWeb.openFiles`, `openFile`, `fileTab`, `chooseFilePanel`, `openWith`, `pinFile`, `closeFile` and `reload` for native file-panel tests. Paths identify tabs by their full workspace-relative name. Tree traversal distinguishes repeated folder names and file basenames.
- Add `ppd web --open-file PATH --with PANEL` for file-panel screenshots.
- `openFile` scrolls long Files trees to find the row. A requested panel without a picker, an unknown panel or a missing file fail with a clear message.
- Without a Paseo host and without `requirements.paseo`, `ppd check` now applies the Paseo 0.15.3 client contract instead of 0.12.0, including the 0.13.0 rules.
- Verify the daemon, compiler and web UI on Paseo 0.15.3. Add an isolated nested-file regression covering panel selection, changes, deletion, restoration, reload and reopening.
- Close the browser when initial app navigation fails.

## 0.2.0 (2026-10-30)

- Verified on Paseo 0.12.0: `ppd daemon up` and `ppd doctor` no longer print the version note on it.
Expand Down
36 changes: 28 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,16 +73,16 @@ $ 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.12.0 app (/Applications/Paseo.app) accepted the plugin
PASS paseo-compile compilePlugin of the Paseo 0.15.3 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 client-eval contributions: addWorkspacePanel, addCommandCenterItem (Paseo 0.15.3 rules)
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.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
PASS lucide-icons 2 icon name(s) valid against 6354 Lucide icons of the Paseo 0.15.3 app (/Applications/Paseo.app)
PASS bundle-size client 3 KiB (1 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.12.0
paseo: 0.15.3
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 @@ -168,6 +168,26 @@ await assertWithinRpcBudget(() => handlers.get("doc.render")!(worstCaseInput));

`paseo-plugin-devkit/web` exports the `PaseoWeb` Playwright page object for your own browser tests.

File-panel tests can use the real Files tree and native tab menu:

```ts
const ui = await PaseoWeb.launch({ url: daemon.url });
try {
await ui.openWorkspace(serverId, workspaceId);
await ui.openFile("reports/live.csv", { panel: "Viewer \u2014 paseo-doc-viewer", remember: true });
await ui.pinFile("reports/live.csv");
await ui.reload();
await ui.openWith("reports/live.csv", "Source \u2014 Paseo");
await ui.closeFile("reports/live.csv");
} finally {
await ui.close();
}
```

Paths are workspace-relative, use `/`, and must not contain `.` or `..` segments. Tab helpers use the full relative path, even when the visible tab shows only its basename. `openFile` focuses an existing tab, otherwise opens through Files, scrolling long trees to find the row. Pass `panel` when a picker is expected; the helper waits up to 10 s for it even when the tab appears first, then fails with a clear error. Panel names accept a unique title or the full host label; an ambiguous title fails instead of choosing a plugin. Omit `panel` when reopening with a saved association; use `openWith` to change it. These helpers target desktop file tabs; compact file sheets can be exercised through `ui.page`.

The CLI accepts the same opening step: `ppd web --workspace <id> --open-file report.pdf --shot report.png`. Add `--with Viewer` for files with a panel picker. `PPD_E2E=1 npx vitest run test/file-panels-e2e.test.ts` exercises duplicate folder and file names, a file below 400 others, a nested CSV, a panel requested without a picker, remembered panel choice, rewrite, deletion, restoration, app reload and tab closure on a fresh isolated daemon; it removes the daemon and temporary workspace on failure too.

## Fake agent

Agent-facing plugins (hooks, timeline cards, injected MCP tools) need agent turns to test. `ppd daemon up --fake-agent` installs `fake-agent`, a credential-free provider plugin ([`assets/fake-agent`](assets/fake-agent)) that runs a scripted turn per prompt. It emits the timeline items real adapters produce, does the file effects for real in the agent's cwd, and calls tools on the MCP servers in its session config (what plugins inject in `before("agent.create")`), over HTTP or stdio. Paseo's own mock provider needs a development build and supports no MCP servers; this replaces it.
Expand Down Expand Up @@ -249,7 +269,7 @@ It also has a weekly job that checks out Paseo main, sets `PASEO_SOURCE` and run

## Compatibility

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.
Verified on macOS with Paseo 0.15.3 (desktop app compiler, CLI and served web UI). CI runs on Linux without Paseo, where daemon tests skip and `ppd check` runs as an approximation. The file-panel lifecycle test uses a real isolated daemon and Chrome; it does not verify the native iOS or Android app.

### React Native, React and Dependabot

Expand Down Expand Up @@ -288,11 +308,11 @@ Review a series upgrade explicitly when the supported host and its React/SDK con
- 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.12 web UI and may need updates when the app changes.
- `ppd web` needs Google Chrome or a Playwright Chromium matching `playwright-core`. Its selectors were exercised on Paseo 0.15.3 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.12.0 (see [Compatibility](#compatibility)).
- macOS and Linux only. Tested on macOS with Paseo 0.15.3 (see [Compatibility](#compatibility)).

## Roadmap

Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/lib/commands.json
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@
"topic": "web",
"usage": "ppd web",
"summary": "open the web UI in Chrome, screenshot, click through",
"help": "ppd web [--shot FILE] [--viewport WxH] [--command TEXT] [--click LABEL]... [options]\n\nOpens the dev daemon's web UI in Chrome (Playwright), opens the only workspace (or --workspace), runs the\nsteps in order and prints console errors.\n\n --shot FILE save a screenshot\n --viewport WxH e.g. 390x844; widths under 768 get the compact (phone) layout with touch\n --command TEXT select a Command Center item by its exact title\n --click LABEL click an element by its accessible name (repeatable)\n --workspace ID workspace id, name or path\n --path /route open an app route instead of a workspace\n --wait MS settle time before the screenshot (default 1500)\n --full-page full-page screenshot\n --headed show the browser\n --name N target dev daemon"
"help": "ppd web [--shot FILE] [--viewport WxH] [--command TEXT] [--click LABEL]... [options]\n\nOpens the dev daemon's web UI in Chrome (Playwright), opens the only workspace (or --workspace), runs the\nsteps in order and prints console errors.\n\n --shot FILE save a screenshot\n --viewport WxH e.g. 390x844; widths under 768 get the compact (phone) layout with touch\n --command TEXT select a Command Center item by its exact title\n --open-file PATH open a workspace-relative file through Paseo's Files tree\n --with PANEL answer the panel picker with a unique panel title or full label (requires --open-file);\n fails when the file opens without a picker (saved association or single panel)\n --click LABEL click an element by its accessible name (repeatable)\n --workspace ID workspace id, name or path\n --path /route open an app route instead of a workspace\n --wait MS settle time before the screenshot (default 1500)\n --full-page full-page screenshot\n --headed show the browser\n --name N target dev daemon"
},
{
"topic": "android",
Expand Down
12 changes: 6 additions & 6 deletions docs-site/src/routes/(docs)/docs/getting-started/+page.svx
Original file line number Diff line number Diff line change
Expand Up @@ -65,19 +65,19 @@ npm run check && npm test
```

```text
PASS manifest my-plugin, requires paseo >=0.12.0
PASS manifest my-plugin, requires paseo >=0.15.3
PASS imports client, server and shared boundaries hold
PASS dependencies no runtime packages
PASS paseo-compile compilePlugin of the Paseo 0.12.0 app (/Applications/Paseo.app) accepted the plugin
PASS paseo-compile compilePlugin of the Paseo 0.15.3 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 client-eval contributions: addWorkspacePanel, addCommandCenterItem (Paseo 0.15.3 rules)
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.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
PASS lucide-icons 2 icon name(s) valid against 6354 Lucide icons of the Paseo 0.15.3 app (/Applications/Paseo.app)
PASS bundle-size client 3 KiB (1 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.12.0
paseo: 0.15.3
workspace created for ~/code/my-plugin
```

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.12.0
paseo: 0.15.3
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
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "paseo-plugin-devkit",
"version": "0.2.0",
"version": "0.3.0",
"description": "Unofficial dev kit for Paseo plugin authors: isolated dev daemon, host-contract checks, a scripted fake agent, web UI screenshots, registry and release helpers, plus a Claude Code skill.",
"keywords": [
"paseo",
Expand Down
3 changes: 3 additions & 0 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,9 @@ steps in order and prints console errors.
--shot FILE save a screenshot
--viewport WxH e.g. 390x844; widths under 768 get the compact (phone) layout with touch
--command TEXT select a Command Center item by its exact title
--open-file PATH open a workspace-relative file through Paseo's Files tree
--with PANEL answer the panel picker with a unique panel title or full label (requires --open-file);
fails when the file opens without a picker (saved association or single panel)
--click LABEL click an element by its accessible name (repeatable)
--workspace ID workspace id, name or path
--path /route open an app route instead of a workspace
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.12.0";
export const VERIFIED_PASEO = "0.15.3";

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

Expand Down
1 change: 1 addition & 0 deletions src/index.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
export * from "./testing.ts";
export { PaseoWeb, parseViewport } from "./web.ts";
export type { FileOpenOptions, LaunchOptions, Viewport } from "./web.ts";
export { daemonUp, daemonDown, daemonStatus, installFakeAgent, readDaemon, requireDaemon } from "./daemon.ts";
export type { DaemonRecord } from "./daemon.ts";
export { installPlugin } from "./install.ts";
Expand Down
Loading
Loading