feat(plugins): split client and server plugin entries (#4206)

* feat(plugins): phase 1 split runtime entries after green gate

The compiler now builds explicit client and server entries, so runtime boundaries are source-owned instead of registration-name filtering. Compiler and runtime tests prove the entry split, directory and suffix boundaries, client Node import errors, migration failure, and client-only operation without a subprocess.

* feat(plugins): phase 2 run client entries after green gate

Explicit client and server contexts replace the mixed plugin context. The app runner owns every client registration and its idempotent removal, including late contributions and composer pills; focused contribution tests prove the removal contract, and all five migrated examples reached running on the isolated worktree daemon.

* feat(cli): phase 3 scaffold runtime split after green gate

The generated project demonstrates the required shared RPC contract, server handler, client surface, and sidebar wiring. The scaffold test and an isolated init, typecheck, install, and running check prove the phase acceptance path.

* docs(plugins): phase 4 publish migration after green gate

Gate: current docs and the paseo-plugin skill describe only explicit client/server entries. The standalone migration guide maps every former registration, and migration-doc.test.ts proves every client add* method remains represented.

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Gate: compiler 13, runtime 24, typecheck, lint, and format passed. The dependency fixture proved node_modules/client was incorrectly treated as a plugin boundary.

* fixup! feat(plugins): phase 2 run client entries after green gate

Gate: client runtime and registry tests, typecheck, lint, format

* fixup! docs(plugins): phase 4 publish migration after green gate

Gate: migration docs test, paragraph audit, typecheck, lint, format

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Gate: compiler organization tests, typecheck, lint, targeted format

* fixup! feat(plugins): phase 2 run client entries after green gate

Gate: shared SDK tests, runtime tests, typecheck, lint, targeted format

* fixup! feat(cli): phase 3 scaffold runtime split after green gate

* fixup! docs(plugins): phase 4 publish migration after green gate

* fixup! feat(plugins): phase 1 split runtime entries after green gate

* docs(plugins): rewrite public plugin docs for runtime entries and mobile guardrails

* fixup! feat(cli): phase 3 scaffold runtime split after green gate

The scaffold now keeps DOM globals out of the program and declares only window.open inside client/web.ts. The scaffold test invokes tsc in a fresh process, proves the generated project passes, and proves a stray document access fails.

* fixup! docs(plugins): phase 4 publish migration after green gate

The internal guide and plugin skill now forbid both the DOM lib and triple-slash DOM references. They direct web adapters to declare only the globals used by client/web.ts.

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Removing the obsolete Babel parser changes the locked npm dependency graph. The macOS Nix desktop gate reported the new fixed-output hash, which this commit records.

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Reject relative imports that escape the plugin root while continuing to skip resolved node_modules internals. The compiler regression test proves the escaped import is rejected and the dependency-internal fixture remains accepted.

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Classify absolute imports and reject plugin-authored paths that escape into node_modules. Dependency internals remain exempt based on their importer path. Red-first compiler regressions cover both bypasses, and the existing dependency fixture remains green.

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Classify canonical esbuild resolution results so dependency-relative and symlink imports cannot escape client/server boundaries. The two compiler regressions failed before the fix and pass afterward.

* test(ci): synchronize flaky state transitions

Wait for repository watcher registration before emitting buffered ref events, let sidebar order polling retry unlaid-out rows, and wait for the inactive browser parking state before screenshot capture. These changes directly address the three observed CI failures; the affected server, Playwright, and desktop browser tests pass locally.

* test(ci): synchronize Mermaid completion layout assertion

The Playwright streaming acceptance test exposed a completion remount between visibility and layout sampling. Check the existing completion promise around the measurement so that transition is not reported as diagram loss.

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Resolve bare package imports before boundary classification so symlinked dependency entries cannot expose server modules to the client bundle. The focused regression proves the bypass and the compiler file passes 20/20.

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Allow canonical paths only within a matching linked package root while preserving runtime and containment checks for imports that leave it. The linked-dependency regression fails before the fix and compiler tests pass 21/21 afterward.

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Reject matching package manifests that contain the plugin or live inside it, so linked-dependency roots cannot exempt plugin or workspace files. The ancestor-manifest regression fails before the fix and compiler tests pass 22/22 afterward.

* fixup! feat(plugins): phase 1 split runtime entries after green gate

Validate plugin-local lexical boundaries before canonical linked-root exemptions and require remembered-root imports to originate inside that root. The linked-root bypass regression fails before the fix and compiler tests pass 23/23 afterward.

packages/cli/src/commands/plugin/scaffold.test.ts

@@ -1,11 +1,27 @@
+import { execFile } from "node:child_process";
 import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { tmpdir } from "node:os";
-import ts from "typescript";
+import { promisify } from "node:util";
 import { afterEach, describe, expect, it } from "vitest";
 import { scaffoldPluginDirectory } from "./scaffold.js";
 
 const directories: string[] = [];
+const execFileAsync = promisify(execFile);
+const tscPath = createRequire(import.meta.url).resolve("typescript/bin/tsc");
+
+async function typecheckPlugin(directory: string): Promise<void> {
+  const configPath = path.join(directory, "tsconfig.json");
+  try {
+    await execFileAsync(process.execPath, [tscPath, "--noEmit", "-p", configPath], {
+      cwd: directory,
+    });
+  } catch (error) {
+    const failure = error as { stderr?: string; stdout?: string };
+    throw new Error(`${failure.stdout ?? ""}${failure.stderr ?? ""}`, { cause: error });
+  }
+}
 
 afterEach(async () => {
   await Promise.all(directories.splice(0).map((directory) => rm(directory, { recursive: true })));
@@ -20,17 +36,12 @@ describe("plugin scaffold", () => {
     await scaffoldPluginDirectory(directory);
 
     const configPath = path.join(directory, "tsconfig.json");
-    const loaded = ts.readConfigFile(configPath, ts.sys.readFile);
-    expect(loaded.error).toBeUndefined();
-    const parsed = ts.parseJsonConfigFileContent(loaded.config, ts.sys, directory);
-    const diagnostics = ts.getPreEmitDiagnostics(
-      ts.createProgram(parsed.fileNames, parsed.options),
-    );
-    expect(
-      diagnostics.map((diagnostic) =>
-        ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
-      ),
-    ).toEqual([]);
+    const config = JSON.parse(await readFile(configPath, "utf8")) as {
+      compilerOptions: { lib: string[]; types: string[] };
+    };
+    expect(config.compilerOptions.lib).toEqual(["ES2023"]);
+    expect(config.compilerOptions.types).toEqual(["react"]);
+    await expect(typecheckPlugin(directory)).resolves.toBeUndefined();
     expect(JSON.parse(await readFile(path.join(directory, "paseo-plugin.json"), "utf8"))).toEqual({
       id: "hello-plugin",
     });
@@ -53,12 +64,38 @@ describe("plugin scaffold", () => {
       },
     });
     expect(await readdir(directory)).not.toContain("paseo-plugin.d.ts");
-    await expect(readFile(path.join(directory, "index.ts"), "utf8")).resolves.toContain(
-      'from "./main.client"',
+    await expect(readFile(path.join(directory, "index.client.tsx"), "utf8")).resolves.toContain(
+      'from "./client/greeting"',
     );
-    await expect(readFile(path.join(directory, "main.client.tsx"), "utf8")).resolves.toContain(
-      "Hello from my plugin",
+    await expect(readFile(path.join(directory, "index.server.ts"), "utf8")).resolves.toContain(
+      'from "./server/greeting"',
     );
+    await expect(readFile(path.join(directory, "client/greeting.tsx"), "utf8")).resolves.toContain(
+      "useRpc(greetingRpc)",
+    );
+    await expect(readFile(path.join(directory, "client/web.ts"), "utf8")).resolves.not.toContain(
+      `/// <reference lib="dom" />`,
+    );
+    await expect(readFile(path.join(directory, "client/web.ts"), "utf8")).resolves.toContain(
+      `declare const window: { open(url: string, target: string, features: string): unknown };`,
+    );
+    await expect(readFile(path.join(directory, "client/web.ts"), "utf8")).resolves.toContain(
+      `Platform.OS === "web"`,
+    );
+    await expect(readFile(path.join(directory, "client/greeting.tsx"), "utf8")).resolves.toContain(
+      `openExternal("https://paseo.sh")`,
+    );
+    await expect(readFile(path.join(directory, "server/greeting.ts"), "utf8")).resolves.toContain(
+      '"Hello, " + name + "!"',
+    );
+    await expect(readFile(path.join(directory, "shared/greeting.ts"), "utf8")).resolves.toContain(
+      'name: "greeting.create"',
+    );
+
+    await writeFile(path.join(directory, "client/greeting.tsx"), '\ndocument.title = "x";\n', {
+      flag: "a",
+    });
+    await expect(typecheckPlugin(directory)).rejects.toThrow("Cannot find name 'document'.");
   });
 
   it("typechecks client and server Paseo API access", async () => {
@@ -68,8 +105,8 @@ describe("plugin scaffold", () => {
     await scaffoldPluginDirectory(directory);
     await Promise.all([
       writeFile(
-        path.join(directory, "inspect.shared.ts"),
-        `import { defineRpc } from "@getpaseo/plugin/server";
+        path.join(directory, "shared", "inspect.ts"),
+        `import { defineRpc } from "@getpaseo/plugin";
 import { z } from "zod";
 
 export const inspect = defineRpc({
@@ -80,13 +117,13 @@ export const inspect = defineRpc({
 `,
       ),
       writeFile(
-        path.join(directory, "inspect.server.ts"),
+        path.join(directory, "server", "inspect.ts"),
         `import type { PluginHandlerContext } from "@getpaseo/plugin/server";
-import type { output as ZodOutput } from "zod";
-import { inspect } from "./inspect.shared";
+import type { RpcInput } from "@getpaseo/plugin";
+import { inspect } from "../shared/inspect";
 
 export async function inspectConfig(
-  _input: ZodOutput<typeof inspect.input>,
+  _input: RpcInput<typeof inspect>,
   { paseo }: PluginHandlerContext,
 ) {
   return { configured: Boolean((await paseo.config.get()).config) };
@@ -94,7 +131,7 @@ export async function inspectConfig(
 `,
       ),
       writeFile(
-        path.join(directory, "main.client.tsx"),
+        path.join(directory, "client", "main.tsx"),
         `import React from "react";
 import { Text } from "react-native";
 import { Icon, Modal, useToast } from "@getpaseo/plugin/react-native";
@@ -107,7 +144,7 @@ import {
   usePaseo,
   useWorkspace,
 } from "@getpaseo/plugin";
-import { inspect } from "./inspect.shared";
+import { inspect } from "../shared/inspect";
 
 export function Surface({ navigation }: PluginSurfaceProps) {
   const paseo = usePaseo();
@@ -155,23 +192,21 @@ export function contributeClient(client: PluginClientContext) {
 `,
       ),
       writeFile(
-        path.join(directory, "index.ts"),
-        `import type { PluginContext } from "@getpaseo/plugin";
-import { AgentPanel, contributeClient, Surface } from "./main.client";
-import { inspectConfig } from "./inspect.server";
-import { inspect } from "./inspect.shared";
+        path.join(directory, "index.client.tsx"),
+        `import type { PluginClientContext } from "@getpaseo/plugin";
+import { AgentPanel, contributeClient, Surface } from "./client/main";
+import { inspect } from "./shared/inspect";
 
-export default function contribute(plugin: PluginContext) {
-  plugin.handle(inspect, inspectConfig);
-  plugin.addSurface("main", Surface);
-  plugin.addWorkspacePanel({
+export default function contribute(client: PluginClientContext) {
+  client.addSurface("main", Surface);
+  client.addWorkspacePanel({
     id: "review",
     title: "Review",
     icon: "Scan",
     context: "agent",
     Component: AgentPanel,
   });
-  plugin.addCommandCenterItem({
+  client.addCommandCenterItem({
     id: "open-review",
     title: "Open review",
     icon: "Scan",
@@ -182,25 +217,25 @@ export default function contribute(plugin: PluginContext) {
       openPanel("review");
     },
   });
-  plugin.addClientSide(contributeClient);
+  return contributeClient(client);
+}
+`,
+      ),
+      writeFile(
+        path.join(directory, "index.server.ts"),
+        `import type { PluginServerContext } from "@getpaseo/plugin";
+import { inspectConfig } from "./server/inspect";
+import { inspect } from "./shared/inspect";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(inspect, inspectConfig);
   return () => {};
 }
 `,
       ),
     ]);
 
-    const configPath = path.join(directory, "tsconfig.json");
-    const loaded = ts.readConfigFile(configPath, ts.sys.readFile);
-    const parsed = ts.parseJsonConfigFileContent(loaded.config, ts.sys, directory);
-    const diagnostics = ts.getPreEmitDiagnostics(
-      ts.createProgram(parsed.fileNames, parsed.options),
-    );
-
-    expect(
-      diagnostics.map((diagnostic) =>
-        ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
-      ),
-    ).toEqual([]);
+    await expect(typecheckPlugin(directory)).resolves.toBeUndefined();
   }, 20_000);
 
   it("refuses to write into a non-empty directory", async () => {

packages/cli/src/commands/plugin/scaffold.ts

@@ -8,7 +8,8 @@ const TSCONFIG = {
     target: "ES2020",
     module: "ESNext",
     moduleResolution: "Bundler",
-    lib: ["ES2023", "DOM"],
+    lib: ["ES2023"],
+    types: ["react"],
     jsx: "react-jsx",
     strict: true,
     skipLibCheck: true,
@@ -19,20 +20,60 @@ const TSCONFIG = {
   include: ["**/*.ts", "**/*.tsx"],
 };
 
-const ENTRY = `import type { PluginContext } from "@getpaseo/plugin";
-import { MainSurface } from "./main.client";
+const CLIENT_ENTRY = `import type { PluginClientContext } from "@getpaseo/plugin";
+import { GreetingSurface } from "./client/greeting";
 
-export default function contribute(plugin: PluginContext) {
-  plugin.addSurface("main", MainSurface);
+export default function contribute(client: PluginClientContext) {
+  client.addSurface("greeting", GreetingSurface);
+  client.addSidebarItem({
+    id: "greeting",
+    title: "Greeting",
+    icon: "MessageCircle",
+    surface: "greeting",
+  });
   return () => {};
 }
 `;
 
-const CLIENT_SURFACE = `import type { PluginSurfaceProps } from "@getpaseo/plugin";
-import React, { useMemo } from "react";
-import { Text, View } from "react-native";
+const SERVER_ENTRY = `import type { PluginServerContext } from "@getpaseo/plugin";
+import { createGreeting } from "./server/greeting";
+import { greetingRpc } from "./shared/greeting";
 
-export function MainSurface({ theme, layout }: PluginSurfaceProps) {
+export default function contribute(server: PluginServerContext) {
+  server.handle(greetingRpc, createGreeting);
+  return () => {};
+}
+`;
+
+const SHARED_GREETING = `import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const greetingRpc = defineRpc({
+  name: "greeting.create",
+  input: z.object({ name: z.string() }),
+  output: z.object({ message: z.string() }),
+});
+`;
+
+const SERVER_GREETING = `import type { RpcInput } from "@getpaseo/plugin";
+import { greetingRpc } from "../shared/greeting";
+
+export function createGreeting({ name }: RpcInput<typeof greetingRpc>) {
+  return { message: "Hello, " + name + "!" };
+}
+`;
+
+const CLIENT_GREETING = `import type { PluginSurfaceProps } from "@getpaseo/plugin";
+import { useRpc } from "@getpaseo/plugin";
+import { useMutation } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { Pressable, Text, View } from "react-native";
+import { greetingRpc } from "../shared/greeting";
+import { openExternal } from "./web";
+
+export function GreetingSurface({ theme, layout }: PluginSurfaceProps) {
+  const createGreeting = useRpc(greetingRpc);
+  const greeting = useMutation({ mutationFn: createGreeting });
   const styles = useMemo(
     () => ({
       screen: {
@@ -41,17 +82,49 @@ export function MainSurface({ theme, layout }: PluginSurfaceProps) {
         backgroundColor: theme.colors.surface0,
       },
       text: { color: theme.colors.foreground },
+      button: { padding: 12, backgroundColor: theme.colors.accent },
+      buttonText: { color: theme.colors.accentForeground },
     }),
     [theme, layout.compact],
   );
   return (
     <View style={styles.screen}>
-      <Text style={styles.text}>Hello from my plugin</Text>
+      <Text style={styles.text}>{greeting.data?.message ?? "Ask the daemon for a greeting."}</Text>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel="Create greeting"
+        style={styles.button}
+        onPress={() => greeting.mutate({ name: "Paseo" })}
+      >
+        <Text style={styles.buttonText}>Create greeting</Text>
+      </Pressable>
+      <Pressable
+        accessibilityRole="link"
+        accessibilityLabel="Open the Paseo website"
+        style={styles.button}
+        onPress={() => openExternal("https://paseo.sh")}
+      >
+        <Text style={styles.buttonText}>Open paseo.sh</Text>
+      </Pressable>
     </View>
   );
 }
 `;
 
+const CLIENT_WEB = `import { Linking, Platform } from "react-native";
+
+// This plugin typechecks without the DOM library. Declare only what this module uses.
+declare const window: { open(url: string, target: string, features: string): unknown };
+
+export async function openExternal(url: string): Promise<void> {
+  if (Platform.OS === "web") {
+    window.open(url, "_blank", "noopener,noreferrer");
+    return;
+  }
+  await Linking.openURL(url);
+}
+`;
+
 export interface PluginScaffold {
   id: string;
   directory: string;
@@ -88,9 +161,16 @@ export async function scaffoldPluginDirectory(
     ["paseo-plugin.json", `${JSON.stringify({ id }, null, 2)}\n`],
     ["package.json", `${JSON.stringify(packageJson, null, 2)}\n`],
     ["tsconfig.json", `${JSON.stringify(TSCONFIG, null, 2)}\n`],
-    ["index.ts", ENTRY],
-    ["main.client.tsx", CLIENT_SURFACE],
+    ["index.client.tsx", CLIENT_ENTRY],
+    ["index.server.ts", SERVER_ENTRY],
+    ["shared/greeting.ts", SHARED_GREETING],
+    ["server/greeting.ts", SERVER_GREETING],
+    ["client/greeting.tsx", CLIENT_GREETING],
+    ["client/web.ts", CLIENT_WEB],
   ]);
+  await Promise.all(
+    ["shared", "server", "client"].map((name) => mkdir(path.join(directory, name))),
+  );
   await Promise.all(
     [...files].map(([filename, contents]) =>
       writeFile(path.join(directory, filename), contents, { flag: "wx" }),