From 2c67c76f8b6a77be7a8666403cc4e153551522eb Mon Sep 17 00:00:00 2001 From: Gabriele Magno Date: Wed, 21 Oct 2026 10:00:15 +0200 Subject: [PATCH 1/4] feat(check): apply the app's file panel rules (getpaseo/paseo#7411) client.addFilePanel ships in Paseo 0.13.0. ppd check failed every plugin that calls it as "not part of the app's plugin client context". The rules now mirror evaluate.ts at e464fd3: id, duplicate, title, icon, the files selector and a function Component (a memo object fails, as in the app). File panel icons follow parsePluginIcon: a Lucide name, { svg } or a component. --- THIRD_PARTY_NOTICES | 9 ++++-- src/check/client-rules.ts | 38 +++++++++++++++++++++- test/check.test.ts | 66 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 109 insertions(+), 4 deletions(-) diff --git a/THIRD_PARTY_NOTICES b/THIRD_PARTY_NOTICES index 7dc3e99..7a1e5e5 100644 --- a/THIRD_PARTY_NOTICES +++ b/THIRD_PARTY_NOTICES @@ -10,8 +10,9 @@ License, Version 2.0. Those portions remain under the Apache License, Version Paseo https://github.com/getpaseo/paseo Copyright (c) 2025-present Mohamed Boudra -Source revision: 9bd58f66b2dfc195898bf1178e84f02933c0d41e -Paseo does not ship a NOTICE file at this revision. +Source revision: 9bd58f66b2dfc195898bf1178e84f02933c0d41e, and +e464fd3bd308e792cd2cf484bd543057b50cb867 (getpaseo/paseo#7411) where marked +below. Paseo does not ship a NOTICE file at either revision. Files with adapted portions, and the Paseo files they come from. Every file listed here starts with a notice naming its sources and describing how it was @@ -20,6 +21,8 @@ under dist/ (for example dist/check/client-rules.js), and the notices are kept. src/check/client-rules.ts packages/app/src/plugins/evaluate.ts + packages/app/src/plugins/evaluate.ts at e464fd3 (addFilePanel) + packages/app/src/plugins/icons.ts at e464fd3 (parsePluginIcon) src/check/manifest.ts packages/server/src/server/plugins/manifest.ts packages/protocol/src/plugin-config.ts @@ -41,7 +44,7 @@ under dist/ (for example dist/check/client-rules.js), and the notices are kept. plugin-examples/provider-direct/server/provider.ts The Paseo license, reproduced verbatim from the LICENSE file at the source -revision above: +revisions above (it is the same at both): -------------------------------------------------------------------------------- diff --git a/src/check/client-rules.ts b/src/check/client-rules.ts index 5c4f41e..2d045b7 100644 --- a/src/check/client-rules.ts +++ b/src/check/client-rules.ts @@ -1,8 +1,11 @@ // Portions adapted from Paseo (https://github.com/getpaseo/paseo) at commit 9bd58f66b2dfc195898bf1178e84f02933c0d41e: // packages/app/src/plugins/evaluate.ts +// The addFilePanel rules are adapted at commit e464fd3bd308e792cd2cf484bd543057b50cb867 (getpaseo/paseo#7411): +// packages/app/src/plugins/evaluate.ts, packages/app/src/plugins/icons.ts (parsePluginIcon) // Copyright (c) 2025-present Mohamed Boudra. Licensed under the Apache License, Version 2.0; see THIRD_PARTY_NOTICES. // Modified: the registration checks are rewritten as a standalone class with no app or React dependencies, take the -// icon set as a parameter, and collect every violation instead of throwing on the first. +// icon set as a parameter, and collect every violation instead of throwing on the first; icons skip the SVG markup +// check. // // The app's client registration rules. The app throws on the first violation and the whole plugin client fails // to evaluate; the only trace is a console.warn("[Plugins] Failed to evaluate ..."). Here every violation is @@ -22,6 +25,7 @@ export const CLIENT_CONTEXT_METHODS = new Set([ "addSidebarFooterItem", "addSurface", "addSidebarItem", + "addFilePanel", "addWorkspacePanel", "addCommandCenterItem", "addSlashCommand", @@ -38,6 +42,17 @@ const isFunction = (value: unknown): boolean => typeof value === "function"; const isComponentType = (value: unknown): boolean => typeof value === "function" || (typeof value === "object" && value !== null && "$$typeof" in value); +const selectorEntries = (entries: unknown, extension: boolean): entries is string[] => + Array.isArray(entries) && + entries.every((entry) => typeof entry === "string" && entry.trim() === entry && entry.length > 0 && !/[\\/*?]/.test(entry) && (!extension || !entry.includes("."))); + +/** A file panel's `files`: only `extensions` (no dots) and optional `filenames`, plain names, at least one in all. */ +function validFileSelector(files: unknown): boolean { + if (!files || typeof files !== "object") return false; + const { extensions, filenames = [], ...rest } = files as Record; + return Object.keys(rest).length === 0 && selectorEntries(extensions, true) && selectorEntries(filenames, false) && extensions.length + filenames.length > 0; +} + /** * Validates registrations like the app's evaluate.ts. `icons` is the app's Lucide name set; null skips the * icon rule (no icon list available). @@ -80,6 +95,17 @@ export class ClientRules { if (!this.icons.has(icon)) this.fail(`Unknown Lucide icon: ${String(name)}`); } + /** parsePluginIcon: a component, `{ svg }` or a Lucide name. The SVG markup itself is not checked. */ + private pluginIcon(owner: string, icon: unknown): void { + if (isComponentType(icon)) return; + if (typeof icon === "string") { + if (icon.trim()) this.icon(icon); + else this.fail(`${owner} has no icon`); + } else if (typeof (icon as { svg?: unknown } | null)?.svg !== "string") { + this.fail(`${owner} has an invalid icon: expected a Lucide icon name, { svg }, or a component`); + } + } + private sidebarItem(section: "header" | "footer", c: Contribution): void { const id = this.id(c.id, `sidebar ${section} item id`); if (!id) return; @@ -126,6 +152,16 @@ export class ClientRules { if (surface) this.legacySidebarSurfaces.push({ id, surface }); return; } + case "addFilePanel": { + const id = this.id(c.id, "file panel id"); + if (!id) return; + this.unique("file-panel", id, "Duplicate file panel"); + if (!text(c.title)) this.fail(`File panel ${id} has no title`); + this.pluginIcon(`File panel ${id}`, c.icon); + if (!validFileSelector(c.files)) this.fail(`File panel ${id} has invalid selector`); + if (!isFunction(c.Component)) this.fail(`File panel ${id} is not a component`); + return; + } case "addWorkspacePanel": { const id = this.id(c.id, "workspace panel id"); if (!id) return; diff --git a/test/check.test.ts b/test/check.test.ts index 2e2c2e4..b5bcc00 100644 --- a/test/check.test.ts +++ b/test/check.test.ts @@ -4,6 +4,7 @@ import { assertWithinRpcBudget, measureRpc } from "../src/check/budget.ts"; import { bundleRequires, disallowedClientRequires, disallowedServerRequires, evaluateClientBundle, evaluateServerBundle } from "../src/check/bundle.ts"; import { compileLikePaseo, findPaseoApp, findPaseoSource } from "../src/check/compile.ts"; import { classSyntaxErrors, findHermes, hermesParse, hermesSmoke } from "../src/check/hermes.ts"; +import { ClientRules } from "../src/check/client-rules.ts"; import { runChecks } from "../src/check/index.ts"; import { manifestFindings } from "../src/check/manifest.ts"; import { appIconNames, parseBundleIconNames, parseLucideNames, staticIconNames } from "../src/check/lucide.ts"; @@ -67,6 +68,71 @@ describe("compiled fixtures", () => { }); }); +describe("file panels (evaluate.ts addFilePanel, getpaseo/paseo#7411)", () => { + const Component = () => null; + const panel = (patch: Record = {}) => ({ id: "pdf", title: "PDF", icon: "FileText", files: { extensions: ["pdf"] }, Component, ...patch }); + const errors = (...panels: unknown[]) => { + const rules = new ClientRules(new Set(["FileText"])); + for (const contribution of panels) rules.register("addFilePanel", [contribution]); + return rules.errors; + }; + + it("accepts extension, filename and mixed selectors, and Lucide, SVG or component icons", () => { + expect( + errors( + panel(), + panel({ id: "make", files: { extensions: [], filenames: ["Makefile", "Dockerfile"] } }), + panel({ id: "docs", files: { extensions: ["md", "MDX"], filenames: ["README"] } }), + panel({ id: "svg", icon: { svg: "" } }), + panel({ id: "drawn", icon: Component }), + ), + ).toEqual([]); + }); + + it.each([ + ["no selector", undefined], + ["an unknown key", { extensions: ["pdf"], globs: ["*.pdf"] }], + ["no extensions list", { filenames: ["Makefile"] }], + ["a leading dot", { extensions: [".pdf"] }], + ["a dotted extension", { extensions: ["tar.gz"] }], + ["an empty entry", { extensions: [""] }], + ["an untrimmed entry", { extensions: [" pdf"] }], + ["a non-string entry", { extensions: [1] }], + ["a path", { extensions: [], filenames: ["docs/README"] }], + ["a backslash", { extensions: [], filenames: ["docs\\README"] }], + ["a glob", { extensions: ["*"] }], + ["a wildcard", { extensions: [], filenames: ["READ?E"] }], + ["filenames that are not a list", { extensions: ["pdf"], filenames: "README" }], + ["no entries", { extensions: [], filenames: [] }], + ])("rejects a selector with %s", (_, files) => { + expect(errors(panel({ files }))).toEqual(["File panel pdf has invalid selector"]); + }); + + it("rejects a bad or duplicate id, no title, a bad icon and a memo component, like the app", () => { + const memo = { $$typeof: Symbol.for("react.memo"), type: Component, compare: null }; + expect( + errors( + panel(), + panel(), + panel({ id: "Bad_Id" }), + panel({ id: "untitled", title: " " }), + panel({ id: "unknown-icon", icon: "NotAnIcon" }), + panel({ id: "no-icon", icon: " " }), + panel({ id: "odd-icon", icon: 1 }), + panel({ id: "memo", Component: memo }), + ), + ).toEqual([ + "Duplicate file panel: pdf", + "Invalid file panel id: Bad_Id", + "File panel untitled has no title", + "Unknown Lucide icon: NotAnIcon", + "File panel no-icon has no icon", + "File panel odd-icon has an invalid icon: expected a Lucide icon name, { svg }, or a component", + "File panel memo is not a component", + ]); + }); +}); + describe("runChecks", () => { it("passes the example plugin on the approximation and labels it as such", async () => { const results = await runChecks(GOOD, { paseoSource: null, paseoApp: null }); From 3083e288094af9b7ffb0f66f422a0ac45d1e0c71 Mon Sep 17 00:00:00 2001 From: Gabriele Magno Date: Wed, 21 Oct 2026 10:00:39 +0200 Subject: [PATCH 2/4] feat(check): warn when requirements.paseo admits apps without a called method Below Paseo 0.13.0 client.addFilePanel is undefined, so an unguarded call throws and the app drops the whole client. The recording client answered every add* call, so ppd check could not see it. When the range admits a release older than a method the client calls (CLIENT_METHOD_SINCE), the client is evaluated again with that method undefined. A throw there is a client-eval warning, and a note in ppd install and ppd dev, naming the range and the fix. --- src/check/bundle.ts | 4 +++- src/check/client-rules.ts | 20 ++++++++++++++++++ src/check/eval-worker.ts | 2 +- src/check/index.ts | 43 ++++++++++++++++++++++++++++++++++++++- src/check/isolate.ts | 4 +++- test/check.test.ts | 34 +++++++++++++++++++++++++++++-- 6 files changed, 101 insertions(+), 6 deletions(-) diff --git a/src/check/bundle.ts b/src/check/bundle.ts index a427638..32a719c 100644 --- a/src/check/bundle.ts +++ b/src/check/bundle.ts @@ -171,6 +171,8 @@ export interface ClientEvaluationOptions { settleMs?: number; /** The app's Lucide names. When given, unknown contribution icons are contract errors, like in the app. */ icons?: ReadonlySet | null; + /** Client methods left undefined, like on an app that predates them (CLIENT_METHOD_SINCE). */ + absentMethods?: readonly string[]; } /** Icon names in a contribution: `icon` fields up to two levels deep (header buttons nest them). */ @@ -205,7 +207,7 @@ export async function evaluateClientBundle(bundle: string, pluginDir: string, op {}, { get: (_, key) => { - if (typeof key !== "string") return undefined; + if (typeof key !== "string" || options.absentMethods?.includes(key)) return undefined; if (/^add[A-Z]/.test(key)) { return (...args: unknown[]) => { rules.register(key, args); diff --git a/src/check/client-rules.ts b/src/check/client-rules.ts index 2d045b7..16de43d 100644 --- a/src/check/client-rules.ts +++ b/src/check/client-rules.ts @@ -10,6 +10,8 @@ // The app's client registration rules. The app throws on the first violation and the whole plugin client fails // to evaluate; the only trace is a console.warn("[Plugins] Failed to evaluate ..."). Here every violation is // collected instead. +import intersects from "semver/ranges/intersects.js"; +import validRange from "semver/ranges/valid.js"; const CONTRIBUTION_ID = /^[a-z][a-z0-9-]*$/; const PANEL_LOCATIONS = ["workspace", "explorer"]; @@ -42,6 +44,24 @@ const isFunction = (value: unknown): boolean => typeof value === "function"; const isComponentType = (value: unknown): boolean => typeof value === "function" || (typeof value === "object" && value !== null && "$$typeof" in value); +/** + * Client context methods that only newer apps have, with the release that added each. Older apps leave them undefined. + * Source: public-docs/plugins/reference.md (addFilePanel: "File panels", getpaseo/paseo#7411). + */ +export const CLIENT_METHOD_SINCE = new Map([["addFilePanel", "0.13.0"]]); + +/** + * The methods among `called` that some app admitted by `range` predates. Apps below the range skip the plugin before + * evaluating it, so only the range matters. Empty for a missing or invalid range (the manifest check reports it). + */ +export function methodsMissingIn(range: unknown, called: Iterable): string[] { + if (typeof range !== "string" || validRange(range) === null) return []; + return [...new Set(called)].filter((method) => { + const since = CLIENT_METHOD_SINCE.get(method); + return since !== undefined && intersects(range, `<${since}`); + }); +} + const selectorEntries = (entries: unknown, extension: boolean): entries is string[] => Array.isArray(entries) && entries.every((entry) => typeof entry === "string" && entry.trim() === entry && entry.length > 0 && !/[\\/*?]/.test(entry) && (!extension || !entry.includes("."))); diff --git a/src/check/eval-worker.ts b/src/check/eval-worker.ts index 6e8b37f..1c61958 100644 --- a/src/check/eval-worker.ts +++ b/src/check/eval-worker.ts @@ -44,7 +44,7 @@ try { ...(await runCleanup(evaluation.cleanup, baseline)), }; } else { - const evaluation = await evaluateClientBundle(bundle, request.pluginDir, { icons: request.icons ? new Set(request.icons) : null }); + const evaluation = await evaluateClientBundle(bundle, request.pluginDir, { icons: request.icons ? new Set(request.icons) : null, absentMethods: request.absentMethods }); result = { target: "client", contributions: evaluation.contributions.map((entry) => entry.method), diff --git a/src/check/index.ts b/src/check/index.ts index dcc99a4..a2aa801 100644 --- a/src/check/index.ts +++ b/src/check/index.ts @@ -2,8 +2,10 @@ import { existsSync, readFileSync } from "node:fs"; import { relative, resolve } from "node:path"; import { parseArgs } from "node:util"; +import compareVersions from "semver/functions/compare.js"; import { bundleRequires, disallowedClientRequires, disallowedServerRequires, formatKb, sizeReport } from "./bundle.ts"; import { compileApprox, CompileError, compileLikePaseo, compileWithHost, describeHost, findEntries, findPaseoApp, findPaseoHost, findPaseoSource, PASEO_COMPILER, PASEO_SOURCE_MISSING } from "./compile.ts"; +import { CLIENT_METHOD_SINCE, methodsMissingIn } from "./client-rules.ts"; import { classSyntaxErrors, findHermes, hermesParse, hermesSmoke } from "./hermes.ts"; import { boundaryFindings, dependencyFindings, externalPackages, pluginFiles, typesNodeFinding } from "./imports.ts"; import { cleanupWarning, DEFAULT_EVAL_TIMEOUT_MS, evaluateIsolated } from "./isolate.ts"; @@ -45,6 +47,40 @@ interface Manifest { [key: string]: unknown; } +interface ClientRun { + contributions: string[]; + contractErrors: string[]; + setupError: string | null; +} + +/** + * Apps below `requirements.paseo` skip the plugin, but one the range admits may predate a client method the + * contribution calls. The method is undefined there, and an unguarded call stops the whole client. Evaluates the + * client once more without those methods; null when it still runs, or when the first run already failed or threw. + */ +async function olderAppWarning(bundle: string, dir: string, range: unknown, run: ClientRun, timeoutMs: number): Promise<{ message: string; thrown: string } | null> { + if (run.contractErrors.length || run.setupError) return null; + const missing = methodsMissingIn(range, run.contributions); + if (!missing.length) return null; + const outcome = await evaluateIsolated("client", bundle, dir, { timeoutMs, absentMethods: missing }); + const result = outcome.ok && !("error" in outcome.result) && outcome.result.target === "client" ? outcome.result : null; + if (!result?.setupError) return null; + const since = missing.map((method) => CLIENT_METHOD_SINCE.get(method)!).sort(compareVersions).at(-1); + const methods = missing.map((method) => `client.${method}`); + return { + message: `on Paseo before ${since}, which requirements.paseo "${String(range)}" admits, ${methods.join(", ")} ${methods.length > 1 ? "are" : "is"} undefined and the contribution throws, so those apps show none of this client. Declare ">=${since}" or guard with ${methods.map((method) => `typeof ${method} === "function"`).join(", ")}`, + thrown: result.setupError, + }; +} + +function manifestRange(dir: string): unknown { + try { + return JSON.parse(readFileSync(resolve(dir, "paseo-plugin.json"), "utf8"))?.requirements?.paseo; + } catch { + return undefined; + } +} + export async function runChecks(pluginDir: string, options: CheckOptions = {}): Promise { const dir = resolve(pluginDir); const results: CheckResult[] = []; @@ -186,8 +222,10 @@ export async function runChecks(pluginDir: string, options: CheckOptions = {}): else if (result.target === "client") { result.icons.forEach((icon) => contributionIcons.add(icon)); const summary = `contributions: ${result.contributions.join(", ") || "none"}`; + const olderApp = await olderAppWarning(clientBundle, dir, manifest.requirements?.paseo, result, evalTimeoutMs); if (result.contractErrors.length) add("client-eval", "fail", "the app would reject this plugin client and show none of its UI", [...result.contractErrors, summary]); else if (result.setupError) add("client-eval", "warn", `contribution threw under stub host modules (may be a stub limit): ${result.setupError}`, [summary]); + else if (olderApp) add("client-eval", "warn", olderApp.message, [`error on those apps: ${olderApp.thrown}`, summary]); else if (cleanupWarning(result)) add("client-eval", "warn", cleanupWarning(result)!, [summary]); else add("client-eval", "pass", summary); } @@ -329,14 +367,17 @@ export async function checkClient(pluginDir: string, options: CheckOptions = {}) } catch (error) { return { errors: [`client compile failed: ${(error as Error).message}`], notes: [], iconSource: null }; } - const outcome = await evaluateIsolated("client", bundle, dir, { timeoutMs: options.evalTimeoutMs ?? DEFAULT_EVAL_TIMEOUT_MS, icons: lucide?.names ?? null }); + const timeoutMs = options.evalTimeoutMs ?? DEFAULT_EVAL_TIMEOUT_MS; + const outcome = await evaluateIsolated("client", bundle, dir, { timeoutMs, icons: lucide?.names ?? null }); const iconSource = lucide?.source ?? null; if (!outcome.ok) return { errors: [outcome.error], notes: [], iconSource }; const result = outcome.result; if ("error" in result) return { errors: [result.error], notes: [], iconSource }; if (result.target !== "client") return null; + const olderApp = await olderAppWarning(bundle, dir, manifestRange(dir), result, timeoutMs); const notes = [ ...(result.setupError ? [`contribution threw under stub host modules (may be a stub limit): ${result.setupError}`] : []), + ...(olderApp ? [olderApp.message] : []), ...(cleanupWarning(result) ? [cleanupWarning(result)!] : []), ...(iconProblem ? [iconProblem] : iconSource ? [] : ["icon names not checked: no Lucide list found"]), ]; diff --git a/src/check/isolate.ts b/src/check/isolate.ts index e346f57..d92d891 100644 --- a/src/check/isolate.ts +++ b/src/check/isolate.ts @@ -16,6 +16,7 @@ export interface EvalRequest { pluginDir: string; resultFile: string; icons: string[] | null; + absentMethods: string[]; } interface CleanupReport { @@ -107,7 +108,7 @@ export async function evaluateIsolated( target: "server" | "client", bundle: string, pluginDir: string, - options: { timeoutMs?: number; icons?: ReadonlySet | null } = {}, + options: { timeoutMs?: number; icons?: ReadonlySet | null; absentMethods?: readonly string[] } = {}, ): Promise { const timeoutMs = options.timeoutMs ?? DEFAULT_EVAL_TIMEOUT_MS; const work = mkdtempSync(join(tmpdir(), "ppd-eval-")); @@ -118,6 +119,7 @@ export async function evaluateIsolated( pluginDir, resultFile: join(work, "result.json"), icons: options.icons ? [...options.icons] : null, + absentMethods: [...(options.absentMethods ?? [])], }; writeFileSync(request.bundleFile, bundle); writeFileSync(join(work, "request.json"), JSON.stringify(request)); diff --git a/test/check.test.ts b/test/check.test.ts index b5bcc00..230223f 100644 --- a/test/check.test.ts +++ b/test/check.test.ts @@ -1,3 +1,4 @@ +import { writeFileSync } from "node:fs"; import { join } from "node:path"; import { describe, expect, it } from "vitest"; import { assertWithinRpcBudget, measureRpc } from "../src/check/budget.ts"; @@ -5,10 +6,10 @@ import { bundleRequires, disallowedClientRequires, disallowedServerRequires, eva import { compileLikePaseo, findPaseoApp, findPaseoSource } from "../src/check/compile.ts"; import { classSyntaxErrors, findHermes, hermesParse, hermesSmoke } from "../src/check/hermes.ts"; import { ClientRules } from "../src/check/client-rules.ts"; -import { runChecks } from "../src/check/index.ts"; +import { checkClient, runChecks } from "../src/check/index.ts"; import { manifestFindings } from "../src/check/manifest.ts"; import { appIconNames, parseBundleIconNames, parseLucideNames, staticIconNames } from "../src/check/lucide.ts"; -import { EXAMPLE, FIXTURES } from "./helpers.ts"; +import { EXAMPLE, FIXTURES, scratch } from "./helpers.ts"; const GOOD = EXAMPLE; const BAD = join(FIXTURES, "bad-plugin"); @@ -133,6 +134,35 @@ describe("file panels (evaluate.ts addFilePanel, getpaseo/paseo#7411)", () => { }); }); +describe("client methods newer than the oldest app requirements.paseo admits", () => { + const call = 'client.addFilePanel({ id: "pdf", title: "PDF", icon: "FileText", files: { extensions: ["pdf"] }, Component: () => null })'; + const plugin = (range: string, body: string) => { + const dir = scratch("ppd-file-panel-"); + writeFileSync(join(dir, "paseo-plugin.json"), JSON.stringify({ id: "file-panel", requirements: { paseo: range } })); + writeFileSync(join(dir, "index.client.ts"), `export default function contribute(client: any) {\n ${body};\n return () => {};\n}\n`); + return dir; + }; + const clientEval = async (dir: string) => (await runChecks(dir, { paseoSource: null, paseoApp: null })).find((r) => r.id === "client-eval"); + + it("warns when an app the range admits lacks the method and the call is unguarded", async () => { + const dir = plugin(">=0.11.2", call); + const warning = + 'on Paseo before 0.13.0, which requirements.paseo ">=0.11.2" admits, client.addFilePanel is undefined and the contribution throws, so those apps show none of this client. Declare ">=0.13.0" or guard with typeof client.addFilePanel === "function"'; + expect(await clientEval(dir)).toEqual({ + id: "client-eval", + status: "warn", + message: warning, + details: ["error on those apps: client.addFilePanel is not a function", "contributions: addFilePanel"], + }); + expect((await checkClient(dir, { paseoSource: null, paseoApp: null }))?.notes).toContain(warning); + }); + + it("passes a guarded call, and an unguarded one when the range starts at the release that added it", async () => { + expect(await clientEval(plugin(">=0.11.2", `if (typeof client.addFilePanel === "function") ${call}`))).toMatchObject({ status: "pass" }); + expect(await clientEval(plugin(">=0.13.0", call))).toMatchObject({ status: "pass", message: "contributions: addFilePanel" }); + }); +}); + describe("runChecks", () => { it("passes the example plugin on the approximation and labels it as such", async () => { const results = await runChecks(GOOD, { paseoSource: null, paseoApp: null }); From dc0c3cd15fd12c8f68a886105492133831d218ae Mon Sep 17 00:00:00 2001 From: Gabriele Magno Date: Wed, 21 Oct 2026 10:01:39 +0200 Subject: [PATCH 3/4] docs: file panels and the 0.13.0 client method warning README, the docs site check page and the skill's host contract list the file panel rules and the requirements.paseo warning; the MIME row now points at file panels on 0.13.0. --- CHANGELOG.md | 2 ++ README.md | 2 +- docs-site/src/routes/(docs)/docs/check/+page.svx | 2 +- skills/paseo-plugin-dev/SKILL.md | 2 +- skills/paseo-plugin-dev/references/host-contract.md | 5 +++-- 5 files changed, 8 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c09312..5a88308 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,8 @@ ## Unreleased - Verified on Paseo 0.12.0: `ppd daemon up` and `ppd doctor` no longer print the version note on it. +- `ppd check` applies the app's file panel rules (`client.addFilePanel`, Paseo 0.13.0, getpaseo/paseo#7411): id, title, icon, `files` selector and a function `Component`. Before, every plugin that called it failed `client-eval`. +- `client-eval` warns when `requirements.paseo` admits a Paseo release that lacks a client method the plugin calls without a guard (`addFilePanel` before 0.13.0): the call throws there and the app drops the whole client. `ppd install` and `ppd dev` print the same warning as a note. ## 0.1.0 (2026-10-18) diff --git a/README.md b/README.md index 750b344..14030fb 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,7 @@ Every command has `ppd --help`. | Compile | Paseo's own `compilePlugin`, from the installed app or `PASEO_SOURCE`; an esbuild replica (labeled `APPROXIMATION`) only when neither is found. Compile errors carry file:line:col. | | Client modules | Bundle requires only host-provided modules; no gesture handler, reanimated, safe-area or Lucide imports. | | Server bundle | Requires only host modules and Node built-ins; evaluated in a child process (Paseo's evaluator inside the 120 s compile step with the app or a checkout, a replica with a 30 s limit on the approximation); registered RPCs listed; the returned cleanup is called and handles it leaves open (servers, timers) are warnings. A `process.exit` or a hang fails. | -| Client eval | Factory runs in a child process against stub host modules, with the app's registration rules: ids, contexts, callbacks, duplicates, icons, cleanup. Any violation fails, because the app then drops the whole client. | +| Client eval | Factory runs in a child process against stub host modules, with the app's registration rules: ids, contexts, callbacks, duplicates, icons, file panel selectors, cleanup. Any violation fails, because the app then drops the whole client. When `requirements.paseo` admits a release without a method the client calls (`addFilePanel` needs 0.13.0), the factory runs again without it, and a throw is a warning. | | Hermes | No class syntax; `hermesc` parse and a smoke run in the Hermes VM when the binaries are found. | | Icons | Every contribution icon exists in the app's Lucide set (read from the app bundle). | | Size, deps, boundaries | Bundle sizes, runtime deps in `dependencies`, client/server import boundaries, `@types/node` range. | diff --git a/docs-site/src/routes/(docs)/docs/check/+page.svx b/docs-site/src/routes/(docs)/docs/check/+page.svx index 3764ec9..b318bea 100644 --- a/docs-site/src/routes/(docs)/docs/check/+page.svx +++ b/docs-site/src/routes/(docs)/docs/check/+page.svx @@ -47,7 +47,7 @@ It exits 1 on any `FAIL`; warnings and skips do not fail. All flags are on [Comm | `client-requires` | The client bundle requires only modules the app provides: the SDK, `react`, `react-native`, `react/jsx-runtime`, `zod`, `@tanstack/react-query`. Gesture handler, reanimated, safe-area, SVG, Lucide and DOM packages are not available to plugins. | | `server-requires` | The server bundle requires only host modules and Node built-ins; any other bare require would resolve from Paseo's install, not your plugin. | | `server-eval` | The server contribution runs in a child process and the RPCs it registered are listed: with the app or a checkout, Paseo's own evaluator runs it inside the compile step (120 s limit); on the approximation, a replica runs it with a 30 s limit. The returned cleanup is called; handles it leaves open (servers, timers) are warnings. A `process.exit`, a hang or a missing cleanup function fails. | -| `client-eval` | The client contribution runs in a child process against stub host modules and the app's registration rules: ids, contexts, titles, callbacks, components, duplicates, icons, the cleanup function, and methods the app's client context does not have. Any violation fails, because the app then drops the whole client. | +| `client-eval` | The client contribution runs in a child process against stub host modules and the app's registration rules: ids, contexts, titles, callbacks, components, duplicates, icons, file panel selectors, the cleanup function, and methods the app's client context does not have. Any violation fails, because the app then drops the whole client. When `requirements.paseo` admits a release that lacks a method the contribution calls (`addFilePanel` before 0.13.0), it runs again without that method; if it throws, that is a warning: declare the newer range or guard the call. | | `hermes-class` | No `class` syntax in the client bundle: it crashes plugin loading on Hermes, the phone JavaScript engine. | | `hermes-parse` | `hermesc` compiles the client bundle. Skipped without `hermesc`. | | `hermes-vm` | The Hermes VM evaluates the bundle and runs the contribution. Skipped without the VM. | diff --git a/skills/paseo-plugin-dev/SKILL.md b/skills/paseo-plugin-dev/SKILL.md index e5f2864..6f504ed 100644 --- a/skills/paseo-plugin-dev/SKILL.md +++ b/skills/paseo-plugin-dev/SKILL.md @@ -30,7 +30,7 @@ These protect the user's real Paseo. Each has a `ppd` guard; keep them when work Run in order. Each step ends on its stated observable. -1. **Contract check**: `ppd check `. Done when there are 0 FAIL. It compiles and evaluates with the installed Paseo app's own compiler and checks icons against the app's Lucide set. Without the app (Linux, CI) it falls back to an esbuild replica and prints `APPROXIMATION`: say so in your report rather than claiming the real host accepted the plugin. `PASEO_SOURCE=` tests against unreleased Paseo instead. +1. **Contract check**: `ppd check `. Done when there are 0 FAIL. It compiles and evaluates with the installed Paseo app's own compiler and checks icons against the app's Lucide set. Without the app (Linux, CI) it falls back to an esbuild replica and prints `APPROXIMATION`: say so in your report rather than claiming the real host accepted the plugin. `PASEO_SOURCE=` tests against unreleased Paseo instead. A `client-eval` WARN naming `requirements.paseo` means an app the range admits lacks a client method you call (file panels need 0.13.0): raise the range or guard the call. 2. **Dev daemon**: `ppd daemon up --workspace --caffeinate`. Done when it prints a URL. It runs detached with a pidfile, so harness time limits do not kill it. Its home is under `$TMPDIR` (on macOS a `/var/folders/...` path, not `/tmp`). 3. **Install**: `ppd install ` (directory) and `ppd install --git` (committed HEAD through the manifest `build`, like a registry install; installed as `-git` next to the directory install). Done when each prints `running` and `client: passes the app's registration rules`, exit 0. `client-rejected` means the app would drop the whole client (an unknown icon, a bad id): fix it before looking at the UI. 4. **Real UI**: `ppd web --shot out/desktop.png --click ""` and `ppd web --viewport 390x844 --shot out/phone.png --command ""`. Done when you have looked at both screenshots and `ppd web` exits 0 with `console errors: none` and `plugin evaluation errors: none`. Console errors alone are not enough: the app reports a client that failed to evaluate only as a warning. diff --git a/skills/paseo-plugin-dev/references/host-contract.md b/skills/paseo-plugin-dev/references/host-contract.md index 4e9eca9..14e1a4d 100644 --- a/skills/paseo-plugin-dev/references/host-contract.md +++ b/skills/paseo-plugin-dev/references/host-contract.md @@ -9,7 +9,8 @@ What Paseo 0.11 and 0.12 actually give a plugin at runtime. `ppd check` tests th | Safe area (checked) | Plugin panels get no safe-area insets (getpaseo/paseo#5866, PR #5867). The Android nav bar can cover the last rows. | Pad the bottom yourself; runtime-detect a host `useSafeAreaInsets` export if one appears. | | Horizontal scroll | A plugin horizontal `ScrollView` is not registered with the host, so a fast right swipe on a zoomed page opens the mobile sidebar. | Known limit; keep horizontal panning short or behind a mode. | | Icons (checked) | Contribution `icon` fields are Lucide names, validated at registration: an unknown name throws, and the app then drops the whole plugin client (every contribution, not only that item) with just a console warning. `Icon` from `/client/react-native` renders nothing for an unknown name. No `lucide-react-native` import. | `ppd check` checks names against the installed app's Lucide set; `ppd install` and `ppd web` report a rejected client. | -| Client registration (checked) | Contribution ids match `/^[a-z][a-z0-9-]*$/` and are unique per kind; `context` and callbacks are validated; the factory must return a cleanup function. Any violation drops the whole client, like an unknown icon. | `ppd check` applies the app's rules. | +| Client registration (checked) | Contribution ids match `/^[a-z][a-z0-9-]*$/` and are unique per kind; `context` and callbacks are validated; file panel selectors list extensions without dots and plain filenames, no paths or wildcards; the factory must return a cleanup function. Any violation drops the whole client, like an unknown icon. | `ppd check` applies the app's rules. | +| Newer client methods (checked) | `client.addFilePanel` exists from Paseo 0.13.0, like the `Loading` and `DocumentFrame` components of `/client/ui`. On an older app the method is undefined, so an unguarded call drops the whole client. Apps below `requirements.paseo` skip the plugin. | Declare `"paseo": ">=0.13.0"`, or guard with `typeof client.addFilePanel === "function"`. `ppd check` warns about an unguarded call the range lets an older app reach; it cannot see `Loading` or `DocumentFrame` used on one. | | Cleanup (checked) | The server contribution must return a cleanup too; it runs when the plugin child shuts down (reload, disable, remove). A server, socket or interval it leaves open can keep the old child alive or its port busy for the next load. | Close everything you open; `ppd check` warns about handles left open after cleanup. | | Hermes (checked) | iOS and Android evaluate the client bundle from source on Hermes. Class syntax fails to parse (getpaseo/paseo#5783), including classes inside bundled dependencies. Paseo lowers async/await for you. | Functions and closures instead of classes; check dependencies too. | | Server bundle (checked) | Compiled to one CJS string and `eval`'d in a plugin subprocess. Bare requires other than host modules and Node built-ins resolve from Paseo's install, not the plugin. WASM must be inlined (a 12.6 MB bundle parsed in about 60 ms). No native addons, no file-path WASM, no assumption of system binaries. | Pure JS/WASM dependencies, bundled. | @@ -18,6 +19,6 @@ What Paseo 0.11 and 0.12 actually give a plugin at runtime. `ppd check` tests th | RPC timeout | 30 s per RPC (`REQUEST_TIMEOUT_MS`). Handlers get no abort signal (hooks do get `context.signal`). After a timeout the handler keeps running and holding memory and concurrency. | Deadline every heavy job (`Promise.race`), cap input sizes, test worst-case fixtures with `assertWithinRpcBudget`. Synchronous WASM cannot be interrupted. | | Crashes | A crashed plugin child is not respawned (getpaseo/paseo#6821). One out-of-memory parse takes the plugin down until `paseo plugin reload`. | Size and decompression caps before parsing; stream large formats. | | Response size | Direct websocket messages cap at 100 MiB; clients behind the relay should budget well under 32 MiB. Large base64 images add up fast. | Page or chunk responses; budget bytes per response. | -| MIME and previews | The daemon labels many binaries `application/octet-stream`; the Files tree has no previewer hook for plugins (getpaseo/paseo#3109, #5930). | Detect formats by magic bytes; provide your own entry points (panel, Command Center item, slash command). | +| MIME and previews | Daemons before 0.13.0 label many binaries, PDFs included, `application/octet-stream`. From 0.13.0 a file panel (`client.addFilePanel`) renders the file tab for the extensions and filenames it claims; before that, plugins have no previewer hook (getpaseo/paseo#3109, #5930). | Detect formats by magic bytes; on 0.13.0 and later register a file panel, otherwise provide your own entry points (panel, Command Center item, slash command). | | Media | No native video primitive (#4562). Host `playAudio` exists from 0.11.2. | Plan media features around what the host exposes. | | Theme and layout | Color every `Text` from `theme.colors`; size layout from `layout.compact`. No HTML elements, no `className`. | Test both `ppd web` viewports. | From b34b1b8b0b6a25bb6f240c6b6130618abda5009b Mon Sep 17 00:00:00 2001 From: Gabriele Magno Date: Wed, 21 Oct 2026 10:10:26 +0200 Subject: [PATCH 4/4] docs(site): file panel selector error and the 0.13.0 client method warning --- .../routes/(docs)/docs/compatibility/+page.svx | 2 +- .../routes/(docs)/docs/troubleshooting/+page.svx | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs-site/src/routes/(docs)/docs/compatibility/+page.svx b/docs-site/src/routes/(docs)/docs/compatibility/+page.svx index f5e4a49..11e22b9 100644 --- a/docs-site/src/routes/(docs)/docs/compatibility/+page.svx +++ b/docs-site/src/routes/(docs)/docs/compatibility/+page.svx @@ -38,7 +38,7 @@ Windows is not supported. | `@getpaseo/client` and `ws` inside `app.asar` | `agentTimeline` | the call fails naming the modules it looked for. | | `paseo daemon run --home`, `PASEO_HOME`, `PASEO_LISTEN` and the `config.json` keys | `ppd daemon up` | a start failure prints the daemon output and how it was started. | | Accessible names in the web UI ("New workspace", "Open menu", "Workspace actions", "Search commands") | `ppd web`, `PaseoWeb` | a timeout names the label it waited for. | -| Rules vendored from Paseo (client registration, manifest schema, build options) | every `ppd check` (`manifest`, `client-eval`), the client check in `ppd install` and `ppd dev`, and the approximation's compile | drift shows up in the weekly CI job against Paseo main. | +| Rules vendored from Paseo (client registration, the release that added each newer client method, manifest schema, build options) | every `ppd check` (`manifest`, `client-eval`), the client check in `ppd install` and `ppd dev`, and the approximation's compile | drift shows up in the weekly CI job against Paseo main. | `ppd daemon up` prints a note when the installed Paseo is not {meta.verifiedPaseo}, and `ppd doctor` shows the same text as a warning on its `paseo CLI` line: diff --git a/docs-site/src/routes/(docs)/docs/troubleshooting/+page.svx b/docs-site/src/routes/(docs)/docs/troubleshooting/+page.svx index fcc33ad..7ec00b3 100644 --- a/docs-site/src/routes/(docs)/docs/troubleshooting/+page.svx +++ b/docs-site/src/routes/(docs)/docs/troubleshooting/+page.svx @@ -32,6 +32,8 @@ prints the same lines and keeps watching. Each line under `client:` is a registr - `Unknown Lucide icon: X`: the app's Lucide build has no icon named X. - `Command Center item X has no icon`, `Workspace panel X has invalid context`, `Screen X is not a component`. +- `File panel X has invalid selector`: `files` takes only `extensions` (without the dot) and `filenames`, plain + names with no `/`, `\`, `*` or `?`, at least one in all. - `client.X is not part of the app's plugin client context (calling it throws)`. - `Plugin contribution must return a cleanup function`. @@ -89,6 +91,19 @@ approximation; with the app or a checkout the server is evaluated inside the com blocking loop at module load or in `contribute` ends here. `plugin code called process.exit(N)` means what it says: the host would lose the whole plugin process. A timer or server left running after the cleanup is a warning, not a failure. +

on Paseo before 0.13.0, client.addFilePanel is undefined

+ +```text +WARN client-eval on Paseo before 0.13.0, which requirements.paseo ">=0.11.2" admits, client.addFilePanel is undefined and the contribution throws, so those apps show none of this client. Declare ">=0.13.0" or guard with typeof client.addFilePanel === "function" + error on those apps: client.addFilePanel is not a function + contributions: addFilePanel +``` + +File panels arrived in Paseo 0.13.0. On an older app the call throws and the app drops the whole client, while apps +below `requirements.paseo` skip the plugin. Declare `"paseo": ">=0.13.0"`, or register the panel only when +`typeof client.addFilePanel === "function"` to keep older apps. `ppd install` and `ppd dev` print the same text as a +`note:` line. +

Dev daemon

no running dev daemon