mirror of
https://github.com/getpaseo/paseo.git
synced 2026-10-14 13:22:37 +00:00
docs(plugins): version breaking API guides (#4245)
Keep stable v0.7 guidance available while the client-entry layout is previewed for v0.8. Existing reference and migration URLs redirect to the release that owns their content.
This commit is contained in:
Mohamed Boudra
+3
-3
@@ -158,7 +158,7 @@ Its controlled modal keeps presentation metadata on `<Modal title="…" icon={
|
||||
`<Modal.Content>`.
|
||||
Plugin UI runs on desktop and mobile across multiple themes: color every `Text` from
|
||||
`theme.colors.foreground` or `theme.colors.foregroundMuted`, and size layout from `layout.compact`.
|
||||
See `public-docs/plugins/reference.md`.
|
||||
See `public-docs/plugins/v0.8/reference.md`.
|
||||
|
||||
| Module | Use it for |
|
||||
| ------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
@@ -176,7 +176,7 @@ The scaffold omits `"DOM"` from `tsconfig.json` and does not use `/// <reference
|
||||
browser globals are not available across the plugin. Put sanctioned web-only APIs in
|
||||
`client/web.ts`, declare only the globals that module uses, gate each export with
|
||||
`Platform.OS === "web"`, and provide a native implementation or no-op. See the
|
||||
[public plugin reference](../public-docs/plugins/reference.md#works-on-mobile) for the complete
|
||||
[public plugin reference](../public-docs/plugins/v0.8/reference.md#works-on-mobile) for the complete
|
||||
pattern.
|
||||
|
||||
```ts
|
||||
@@ -417,7 +417,7 @@ stable rather than arrival-ordered. The app resolves that id
|
||||
against the installed catalog on every change; an id nothing contributes falls back to the default
|
||||
preference instead of painting the reserved slot's placeholder colors.
|
||||
|
||||
Existing plugin authors should follow the standalone [runtime-entry migration guide](../public-docs/plugins/migration.md).
|
||||
Existing plugin authors should follow the standalone [v0.8 runtime-entry migration guide](../public-docs/plugins/v0.8/migration.md).
|
||||
|
||||
See `plugin-examples/local-plugin` for a native surface, `plugin-examples/linear` for a complete
|
||||
attachment-source example, `plugin-examples/timeline-items` for timeline projection, and
|
||||
|
||||
@@ -9,7 +9,7 @@ describe("plugin runtime-entry migration guide", () => {
|
||||
if (!context) throw new Error("PluginClientContext was not found");
|
||||
const methods = [...context.matchAll(/^\s+(add[A-Z]\w*)\(/gm)].map((match) => match[1]);
|
||||
const migration = await readFile(
|
||||
fileURLToPath(new URL("../../../public-docs/plugins/migration.md", import.meta.url)),
|
||||
fileURLToPath(new URL("../../../public-docs/plugins/v0.8/migration.md", import.meta.url)),
|
||||
"utf8",
|
||||
);
|
||||
const table = migration.slice(
|
||||
|
||||
@@ -507,7 +507,7 @@ export default function contribute(plugin: unknown) {
|
||||
"Plugin entry split is required",
|
||||
);
|
||||
await expect(runtime.startPlugin("legacy", directory)).rejects.toThrow(
|
||||
"https://paseo.sh/docs/plugins/migration",
|
||||
"https://paseo.sh/docs/plugins/v0.8/migration",
|
||||
);
|
||||
});
|
||||
|
||||
|
||||
@@ -207,7 +207,7 @@ async function resolveEntryPaths(directory: string): Promise<{
|
||||
const legacyEntry = await findEntry(directory, ["index.ts", "index.tsx"]);
|
||||
if (legacyEntry) {
|
||||
throw new Error(
|
||||
"Plugin entry split is required: migrate index.ts to index.client.tsx and/or index.server.ts. See https://paseo.sh/docs/plugins/migration",
|
||||
"Plugin entry split is required: migrate index.ts to index.client.tsx and/or index.server.ts. See https://paseo.sh/docs/plugins/v0.8/migration",
|
||||
);
|
||||
}
|
||||
throw new Error(
|
||||
|
||||
@@ -157,6 +157,17 @@ export function getDoc(slug: string): Doc | undefined {
|
||||
return getDocs().find((d) => d.slug === slug);
|
||||
}
|
||||
|
||||
const legacyPluginDocRedirects: Readonly<Record<string, string>> = {
|
||||
"/docs/plugins/reference": "/docs/plugins/v0.7/reference",
|
||||
"/docs/plugins/reference.md": "/docs/plugins/v0.7/reference.md",
|
||||
"/docs/plugins/migration": "/docs/plugins/v0.8/migration",
|
||||
"/docs/plugins/migration.md": "/docs/plugins/v0.8/migration.md",
|
||||
};
|
||||
|
||||
export function getLegacyDocsRedirect(pathname: string): string | undefined {
|
||||
return legacyPluginDocRedirects[pathname];
|
||||
}
|
||||
|
||||
function formatLabel(segment: string): string {
|
||||
return segment.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
|
||||
}
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { buildDocsNavTree, getDocs, getLegacyDocsRedirect } from "./docs";
|
||||
|
||||
describe("versioned plugin documentation", () => {
|
||||
it("keeps current and preview releases together in the Plugins navigation", () => {
|
||||
const plugins = buildDocsNavTree(getDocs()).find(
|
||||
(node) => node.type === "category" && node.label === "Plugins",
|
||||
);
|
||||
|
||||
expect(plugins).toMatchObject({
|
||||
type: "category",
|
||||
children: [
|
||||
{ type: "page", label: "Versions", href: "/docs/plugins" },
|
||||
{
|
||||
type: "group",
|
||||
label: "Paseo v0.7 — Current",
|
||||
href: "/docs/plugins/v0.7",
|
||||
children: [{ type: "page", label: "Reference", href: "/docs/plugins/v0.7/reference" }],
|
||||
},
|
||||
{
|
||||
type: "group",
|
||||
label: "Paseo v0.8 — Preview",
|
||||
href: "/docs/plugins/v0.8",
|
||||
children: [
|
||||
{ type: "page", label: "Reference", href: "/docs/plugins/v0.8/reference" },
|
||||
{ type: "page", label: "Migration", href: "/docs/plugins/v0.8/migration" },
|
||||
],
|
||||
},
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
it("keeps existing plugin documentation URLs working", () => {
|
||||
expect(getLegacyDocsRedirect("/docs/plugins/reference")).toBe("/docs/plugins/v0.7/reference");
|
||||
expect(getLegacyDocsRedirect("/docs/plugins/reference.md")).toBe(
|
||||
"/docs/plugins/v0.7/reference.md",
|
||||
);
|
||||
expect(getLegacyDocsRedirect("/docs/plugins/migration")).toBe("/docs/plugins/v0.8/migration");
|
||||
expect(getLegacyDocsRedirect("/docs/plugins/migration.md")).toBe(
|
||||
"/docs/plugins/v0.8/migration.md",
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -1,7 +1,7 @@
|
||||
import startEntry from "@tanstack/react-start/server-entry";
|
||||
import { getAndroidVersionCode } from "~/android-version";
|
||||
import { getCanonicalRedirect } from "~/canonical-url";
|
||||
import { getDoc } from "~/docs";
|
||||
import { getDoc, getLegacyDocsRedirect } from "~/docs";
|
||||
import { getLatestAndroidVersion } from "~/latest-release";
|
||||
import { buildLlmsTxt } from "~/llms";
|
||||
|
||||
@@ -80,6 +80,12 @@ export default {
|
||||
return Response.redirect(url.toString(), 301);
|
||||
}
|
||||
|
||||
const legacyDocsRedirect = getLegacyDocsRedirect(url.pathname);
|
||||
if (legacyDocsRedirect) {
|
||||
url.pathname = legacyDocsRedirect;
|
||||
return Response.redirect(url.toString(), 301);
|
||||
}
|
||||
|
||||
if (url.pathname === "/llms.txt") {
|
||||
return markdownResponse(buildLlmsTxt());
|
||||
}
|
||||
|
||||
+1
-1
@@ -168,7 +168,7 @@ paseo plugin remove my-plugin
|
||||
GitHub shorthand checks an existing host directory first. Append `:<directory>` for a plugin in a
|
||||
monorepo. `paseo plugin logs <id>` returns the plugin's recent daemon-side stdout and stderr. Add `--json` for
|
||||
structured entries, or run `paseo --host <target> plugin logs <id>` for another daemon. See the
|
||||
[Plugin reference](/docs/plugins/reference) for installation, trust, lifecycle, and log-retention
|
||||
[Plugin reference](/docs/plugins/v0.7/reference) for installation, trust, lifecycle, and log-retention
|
||||
behavior.
|
||||
|
||||
## Listing agents
|
||||
|
||||
+12
-259
@@ -1,268 +1,21 @@
|
||||
---
|
||||
title: Plugin quickstart
|
||||
description: Build, install, share, and update a trusted Paseo plugin.
|
||||
nav: Quickstart
|
||||
order: 45
|
||||
title: Paseo plugin documentation
|
||||
description: Choose the plugin API documentation for your Paseo release.
|
||||
nav: Versions
|
||||
order: 44
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Plugin quickstart
|
||||
# Paseo plugin documentation
|
||||
|
||||
> **Experimental:** The plugin API is still evolving, so expect breaking changes and updates to
|
||||
> your plugins as Paseo evolves. See the [plugin roadmap](https://github.com/getpaseo/paseo/labels/plugins)
|
||||
> for planned contribution surfaces.
|
||||
Choose the documentation that matches your Paseo release. The plugin API is experimental and can
|
||||
change between releases.
|
||||
|
||||
A plugin is a TypeScript project installed into one Paseo daemon. It can add
|
||||
[surfaces and sidebar items](/docs/plugins/reference#surfaces-and-sidebar-items),
|
||||
[workspace panels](/docs/plugins/reference#workspace-panels),
|
||||
[Command Center items](/docs/plugins/reference#command-center-items),
|
||||
[slash commands](/docs/plugins/reference#slash-commands),
|
||||
[composer pills](/docs/plugins/reference#composer-pills),
|
||||
[timeline items](/docs/plugins/reference#timeline-items),
|
||||
[themes](/docs/plugins/reference#contribute-a-theme),
|
||||
[attachment sources](/docs/plugins/reference#add-a-composer-attachment-source), and
|
||||
[daemon-side RPCs](/docs/plugins/reference#add-plugin-specific-backend-behavior). Client
|
||||
contributions run on every Paseo client connected to that daemon, including mobile.
|
||||
## [Paseo v0.7 — Current](/docs/plugins/v0.7)
|
||||
|
||||
This guide scaffolds a plugin, runs it, and adds a workspace panel to it.
|
||||
Build and maintain plugins for the latest stable Paseo release.
|
||||
|
||||
## Create a plugin
|
||||
## [Paseo v0.8 — Preview](/docs/plugins/v0.8)
|
||||
|
||||
Use an absolute path on the daemon machine:
|
||||
|
||||
```bash
|
||||
paseo plugin init /absolute/path/to/workspace-plugin
|
||||
cd /absolute/path/to/workspace-plugin
|
||||
npm install
|
||||
```
|
||||
|
||||
`init` writes a strict TypeScript project and does not run the package manager. `npm install` adds
|
||||
development dependencies for typechecking and tests only; Paseo supplies the plugin SDK, React,
|
||||
React Native, TanStack Query, and Zod at runtime.
|
||||
|
||||
The scaffold is a working plugin: a sidebar surface with a button that asks the daemon for a
|
||||
greeting through an RPC.
|
||||
|
||||
```text
|
||||
workspace-plugin/
|
||||
paseo-plugin.json # { "id": "workspace-plugin" }
|
||||
index.client.tsx # runs in the Paseo app
|
||||
index.server.ts # runs in a daemon subprocess
|
||||
client/greeting.tsx # the surface component
|
||||
client/web.ts # the only file allowed to touch browser APIs
|
||||
server/greeting.ts # the RPC handler
|
||||
shared/greeting.ts # the RPC contract, imported by both
|
||||
package.json
|
||||
tsconfig.json
|
||||
```
|
||||
|
||||
Each entry default-exports one function that registers contributions and returns a cleanup
|
||||
function. `index.client.tsx` registers the surface and the sidebar item that opens it:
|
||||
|
||||
```tsx
|
||||
import type { PluginClientContext } from "@getpaseo/plugin";
|
||||
import { GreetingSurface } from "./client/greeting";
|
||||
|
||||
export default function contribute(client: PluginClientContext) {
|
||||
client.addSurface("greeting", GreetingSurface);
|
||||
client.addSidebarItem({
|
||||
id: "greeting",
|
||||
title: "Greeting",
|
||||
icon: "MessageCircle",
|
||||
surface: "greeting",
|
||||
});
|
||||
return () => {};
|
||||
}
|
||||
```
|
||||
|
||||
`index.server.ts` registers the handler for the contract in `shared/greeting.ts`:
|
||||
|
||||
```ts
|
||||
import type { PluginServerContext } from "@getpaseo/plugin";
|
||||
import { createGreeting } from "./server/greeting";
|
||||
import { greetingRpc } from "./shared/greeting";
|
||||
|
||||
export default function contribute(server: PluginServerContext) {
|
||||
server.handle(greetingRpc, createGreeting);
|
||||
return () => {};
|
||||
}
|
||||
```
|
||||
|
||||
The directory is the boundary. Code under `client/` compiles only into the app bundle, code under
|
||||
`server/` only into the daemon bundle, and `shared/` into both. Importing across that line, adding
|
||||
a code file at the root, or importing a `node:` module from client code is a compile error. A
|
||||
plugin with no daemon-side work can omit `index.server.ts`; a plugin with no UI can omit
|
||||
`index.client.tsx`.
|
||||
|
||||
Client code runs on phones as well as in browsers. The project typechecks without the DOM library,
|
||||
so `document` and `window` are errors outside `client/web.ts`, which shows how to gate a browser
|
||||
API behind `Platform.OS` with a native fallback. See
|
||||
[Cross-platform rules](/docs/plugins/reference#cross-platform-rules) before writing UI.
|
||||
|
||||
## Install and try it
|
||||
|
||||
Plugins are trusted, unsandboxed code: server code and Git preparation commands run with the daemon
|
||||
user's access on the daemon machine, and client code runs inside the Paseo app. Installing a plugin
|
||||
means you trust that codebase, its dependencies, and its future updates.
|
||||
|
||||
Turn on **Enable plugins** under **Settings → Plugins** on the daemon you are installing into. It is
|
||||
the global switch for every plugin on that daemon. It is also the root `pluginsEnabled` field in the
|
||||
daemon's `config.json`; after editing the file, apply it with `paseo reload --json`. An automated
|
||||
tool must read the current value and get your explicit permission before turning it on.
|
||||
|
||||
Then typecheck and install:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
paseo plugin install /absolute/path/to/workspace-plugin
|
||||
paseo plugin ls
|
||||
```
|
||||
|
||||
`paseo plugin ls` should report the plugin as `running`. Open Paseo, choose **Greeting** in the
|
||||
sidebar, and press **Create greeting**. The message comes back from the daemon subprocess through
|
||||
the RPC.
|
||||
|
||||
If the sidebar item is missing, check that **Enable plugins** is on, the plugin is `running`, and
|
||||
the client is viewing the host you installed into. `paseo plugin logs workspace-plugin` shows the
|
||||
daemon-side output, including load errors.
|
||||
|
||||
## Add a workspace panel
|
||||
|
||||
A workspace panel opens as a tab next to agents, terminals, and files. Create `client/overview.tsx`:
|
||||
|
||||
```tsx
|
||||
import { type PluginWorkspacePanelProps, useWorkspace } from "@getpaseo/plugin";
|
||||
import { useMemo } from "react";
|
||||
import { Text, View } from "react-native";
|
||||
|
||||
export function WorkspaceOverview({ theme, layout, workspaceId }: PluginWorkspacePanelProps) {
|
||||
const workspace = useWorkspace(workspaceId, ({ name, directory }) => ({
|
||||
name,
|
||||
directory,
|
||||
}));
|
||||
const styles = useMemo(
|
||||
() => ({
|
||||
screen: {
|
||||
flex: 1,
|
||||
padding: layout.compact ? 16 : 24,
|
||||
gap: layout.compact ? 8 : 12,
|
||||
backgroundColor: theme.colors.surface0,
|
||||
},
|
||||
title: { color: theme.colors.foreground, fontSize: layout.compact ? 20 : 24 },
|
||||
label: { color: theme.colors.foregroundMuted },
|
||||
detail: { color: theme.colors.foreground },
|
||||
}),
|
||||
[theme, layout.compact],
|
||||
);
|
||||
|
||||
return (
|
||||
<View style={styles.screen}>
|
||||
<Text style={styles.title}>{workspace?.name}</Text>
|
||||
<Text style={styles.label}>Directory</Text>
|
||||
<Text style={styles.detail}>{workspace?.directory}</Text>
|
||||
</View>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
`useWorkspace` reads the fields the panel renders from the app's cached state, without an RPC and
|
||||
without re-rendering when unrelated fields change. Every `Text` takes its color from
|
||||
`theme.colors`, and `layout.compact` drives spacing, so the panel works in every Paseo theme and on
|
||||
phones. See [Theme and layout](/docs/plugins/reference#theme-and-layout) for the token list.
|
||||
|
||||
Register the panel and a Command Center item that opens it by adding to `index.client.tsx`:
|
||||
|
||||
```tsx
|
||||
import { WorkspaceOverview } from "./client/overview";
|
||||
|
||||
// Inside contribute(client), after the existing registrations:
|
||||
client.addWorkspacePanel({
|
||||
id: "overview",
|
||||
title: "Workspace overview",
|
||||
icon: "PanelsTopLeft",
|
||||
context: "workspace",
|
||||
locations: ["workspace", "explorer"],
|
||||
Component: WorkspaceOverview,
|
||||
});
|
||||
client.addCommandCenterItem({
|
||||
id: "open-overview",
|
||||
title: "Open workspace overview",
|
||||
icon: "PanelsTopLeft",
|
||||
context: "workspace",
|
||||
onSelect({ openPanel }) {
|
||||
openPanel("overview");
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
`icon` is a [Lucide](https://lucide.dev/icons/) icon name.
|
||||
|
||||
## Edit and reload
|
||||
|
||||
Source changes take effect only when you reload the plugin:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
paseo plugin reload workspace-plugin
|
||||
```
|
||||
|
||||
A reload stops the old plugin, runs its cleanup, compiles the current source, and starts it again.
|
||||
A failed reload stays failed and reports its error in `paseo plugin ls`; fix the source and reload
|
||||
again.
|
||||
|
||||
Open a workspace, press **⌘K** on macOS or **Ctrl+K** on Windows and Linux, and choose **Open
|
||||
workspace overview**. The panel opens as a workspace tab.
|
||||
|
||||
## Install a published plugin
|
||||
|
||||
Plugins published in a Git repository install by shorthand or URL:
|
||||
|
||||
```bash
|
||||
paseo plugin add owner/repository
|
||||
paseo plugin add https://gitlab.com/group/repository.git
|
||||
paseo plugin add owner/monorepo:plugins/workspace
|
||||
paseo plugin add owner/repository --ref main
|
||||
```
|
||||
|
||||
Append `:relative/path` when the plugin lives below the repository root. Without `--ref`, the
|
||||
default branch is tracked; a branch tracks updates, while a tag or commit stays pinned.
|
||||
|
||||
```bash
|
||||
paseo plugin status
|
||||
paseo plugin update workspace-plugin
|
||||
paseo plugin update --all
|
||||
```
|
||||
|
||||
Paseo compiles TypeScript itself, so most plugins need no build step. A repository that must
|
||||
install a dependency Paseo does not provide, or generate files, declares
|
||||
[`build` commands](/docs/plugins/reference#cli-reference) in its manifest.
|
||||
|
||||
## Read backend logs
|
||||
|
||||
Daemon-side handlers and cleanup can use normal Node logging:
|
||||
|
||||
```ts
|
||||
console.log("Refreshing issues");
|
||||
console.error("Issue refresh failed", error);
|
||||
```
|
||||
|
||||
Read the recent output from **Settings → Plugins → Logs** or the CLI:
|
||||
|
||||
```bash
|
||||
paseo plugin logs workspace-plugin
|
||||
paseo plugin logs workspace-plugin --json
|
||||
```
|
||||
|
||||
The tail includes `[paseo]` loading, ready, stopping, and stopped entries, plus compilation and load
|
||||
failures, and it survives reloads and crashes. Client-side output stays in the app. See
|
||||
[Debug backend output](/docs/plugins/reference#debug-backend-output) for retention and what not to
|
||||
log.
|
||||
|
||||
## Next
|
||||
|
||||
- [Plugin reference](/docs/plugins/reference): every contribution type, its fields, the runtime
|
||||
modules, hosts, and the CLI.
|
||||
- [Migrate a plugin to runtime entries](/docs/plugins/migration): move a plugin written against the
|
||||
single `index.ts` entry, step by step.
|
||||
- [TypeScript SDK](/docs/sdk): the workspace, agent, provider, and config API available as `paseo`
|
||||
in client and server code.
|
||||
Prepare plugins for the upcoming client and server entry layout. Existing plugin authors should
|
||||
follow the [v0.8 migration guide](/docs/plugins/v0.8/migration).
|
||||
|
||||
@@ -0,0 +1,204 @@
|
||||
---
|
||||
title: Plugin quickstart
|
||||
description: Build, install, share, and update a trusted Paseo plugin.
|
||||
nav: Paseo v0.7 — Current
|
||||
order: 45
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Plugin quickstart
|
||||
|
||||
> **For Paseo v0.7.x.** This is the current stable plugin API.
|
||||
|
||||
> **Experimental:** The plugin API is still evolving, so expect breaking changes and updates to
|
||||
> your plugins as Paseo evolves.
|
||||
|
||||
See the [plugin roadmap](https://github.com/getpaseo/paseo/labels/plugins) for planned contribution
|
||||
surfaces and their current status.
|
||||
|
||||
Paseo plugins add native workspace panels, composer pills, Command Center items, global surfaces, app themes, daemon behavior, and composer attachment sources. They run on every Paseo client connected to the host, including mobile.
|
||||
|
||||
> **Trust every plugin you add.** `paseo plugin add` and `paseo plugin install` mean “I trust this codebase.” Server code and Git preparation commands run unsandboxed with the daemon user's access on the daemon host; client contributions run inside Paseo. Dependencies and future updates are part of that decision. With `--host`, commands run on the remote daemon host.
|
||||
|
||||
On the target host, open **Settings → Plugins** and turn on **Enable plugins**. This is the global switch for every configured plugin on that daemon.
|
||||
|
||||
You can also change the root `pluginsEnabled` field in the daemon's `config.json`, then apply it without restarting:
|
||||
|
||||
```bash
|
||||
paseo reload --json
|
||||
```
|
||||
|
||||
Enabling starts configured plugins; disabling tears them down. Automation must inspect the current value first and obtain your explicit permission before changing a disabled or omitted value to `true`.
|
||||
|
||||
## Create a plugin
|
||||
|
||||
Use an absolute path on the daemon machine:
|
||||
|
||||
```bash
|
||||
paseo plugin init /absolute/path/to/workspace-plugin
|
||||
cd /absolute/path/to/workspace-plugin
|
||||
npm install
|
||||
```
|
||||
|
||||
`init` creates a strict TypeScript project. It does not run the package manager. `npm install`
|
||||
installs development dependencies for local typechecking and tests. Paseo supplies the plugin SDK,
|
||||
React, React Native, TanStack Query, and Zod at runtime; plugins do not need a `build` hook for these
|
||||
modules. `index.ts` registers contributions; client UI lives in `*.client.tsx` files.
|
||||
|
||||
Plugins run on desktop, browser, iOS, and Android. Paseo ships several themes. Color every `Text` from `theme.colors.foreground` or `theme.colors.foregroundMuted`, and size layout from `layout.compact`. Hardcoded black text fails in dark themes.
|
||||
|
||||
Replace `main.client.tsx` with:
|
||||
|
||||
```tsx
|
||||
import { type PluginWorkspacePanelProps, useWorkspace } from "@getpaseo/plugin";
|
||||
import { useMemo } from "react";
|
||||
import { Text, View } from "react-native";
|
||||
|
||||
export function WorkspaceOverview({ theme, layout, workspaceId }: PluginWorkspacePanelProps) {
|
||||
const workspace = useWorkspace(workspaceId, ({ name, directory }) => ({
|
||||
name,
|
||||
directory,
|
||||
}));
|
||||
const styles = useMemo(
|
||||
() => ({
|
||||
screen: {
|
||||
flex: 1,
|
||||
padding: layout.compact ? 16 : 24,
|
||||
gap: layout.compact ? 8 : 12,
|
||||
backgroundColor: theme.colors.surface0,
|
||||
},
|
||||
title: { color: theme.colors.foreground, fontSize: layout.compact ? 20 : 24 },
|
||||
label: { color: theme.colors.foregroundMuted },
|
||||
detail: { color: theme.colors.foreground },
|
||||
}),
|
||||
[theme, layout.compact],
|
||||
);
|
||||
|
||||
return (
|
||||
<View style={styles.screen}>
|
||||
<Text style={styles.title}>{workspace?.name}</Text>
|
||||
<Text style={styles.label}>Directory</Text>
|
||||
<Text style={styles.detail}>{workspace?.directory}</Text>
|
||||
</View>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Replace `index.ts` with:
|
||||
|
||||
```ts
|
||||
import type { PluginContext } from "@getpaseo/plugin";
|
||||
import { WorkspaceOverview } from "./main.client";
|
||||
|
||||
export default function contribute(plugin: PluginContext) {
|
||||
plugin.addWorkspacePanel({
|
||||
id: "overview",
|
||||
title: "Workspace overview",
|
||||
icon: "PanelsTopLeft",
|
||||
context: "workspace",
|
||||
locations: ["workspace", "explorer"],
|
||||
Component: WorkspaceOverview,
|
||||
});
|
||||
plugin.addCommandCenterItem({
|
||||
id: "open-overview",
|
||||
title: "Open workspace overview",
|
||||
icon: "PanelsTopLeft",
|
||||
context: "workspace",
|
||||
onSelect({ openPanel }) {
|
||||
openPanel("overview");
|
||||
},
|
||||
});
|
||||
return () => {};
|
||||
}
|
||||
```
|
||||
|
||||
The icon is a [Lucide](https://lucide.dev/icons/) icon name. `*.client.tsx` files can use React Native runtime APIs; Paseo excludes them from the daemon bundle. Panel props contain stable IDs; `useWorkspace` selects the cached fields the component needs without fetching through RPC or re-rendering for unrelated workspace changes. See [Theme and layout](/docs/plugins/v0.7/reference#theme-and-layout) for the required tokens.
|
||||
|
||||
## Check and install it
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
paseo plugin install /absolute/path/to/workspace-plugin
|
||||
paseo plugin ls
|
||||
```
|
||||
|
||||
Open a workspace, press **⌘K** on macOS or **Ctrl+K** on Windows and Linux, and choose **Open workspace overview**. It opens as a normal workspace tab. If the item does not appear, confirm that **Enable plugins** is on, the plugin status is `running` in `paseo plugin ls`, and the client is viewing the host where you installed it.
|
||||
|
||||
To install a plugin published through GitHub or another Git host:
|
||||
|
||||
```bash
|
||||
paseo plugin add owner/repository
|
||||
paseo plugin add https://gitlab.com/group/repository.git
|
||||
paseo plugin add https://git.example.com/owner/repository.git
|
||||
paseo plugin add owner/monorepo:plugins/workspace
|
||||
paseo plugin add owner/repository --ref main
|
||||
```
|
||||
|
||||
Append `:relative/path` to the source when the plugin lives below the repository root.
|
||||
|
||||
An omitted `--ref` tracks the default branch. Explicit branches track updates; tags and commits are
|
||||
pinned. Check and apply updates with:
|
||||
|
||||
```bash
|
||||
paseo plugin status
|
||||
paseo plugin update workspace-plugin
|
||||
paseo plugin update --all
|
||||
```
|
||||
|
||||
Most plugins should omit `build`. Paseo compiles TypeScript and TSX and supplies its runtime modules.
|
||||
Declare preparation only when the staged checkout must install another dependency, generate source,
|
||||
or perform another required build step:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "workspace-plugin",
|
||||
"build": [
|
||||
["npm", "ci"],
|
||||
["npm", "run", "build"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Each `build` entry is a non-empty argv array, executed directly without a shell from the staged
|
||||
plugin directory. Paseo never chooses a package manager or infers commands from lockfiles. On
|
||||
install and update it resolves the exact commit, runs these commands, then validates, compiles, and
|
||||
activates the candidate. A failed command discards the candidate and keeps the installed/running
|
||||
version. The daemon log records the exact argv and output; `--host` runs them on the remote daemon
|
||||
host.
|
||||
|
||||
## Edit and reload
|
||||
|
||||
Source changes are explicit:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
paseo plugin reload workspace-plugin
|
||||
```
|
||||
|
||||
A reload stops the old plugin, runs its cleanup, compiles the current source, and starts it again. A failed reload stays failed and reports its load error; fix the source and reload again.
|
||||
|
||||
## Debug backend output
|
||||
|
||||
Use normal Node logging in daemon-side handlers and cleanup:
|
||||
|
||||
```ts
|
||||
console.log("Refreshing issues");
|
||||
console.error("Issue refresh failed", error);
|
||||
```
|
||||
|
||||
Read recent stdout and stderr from **Settings → Plugins → Logs** or the CLI:
|
||||
|
||||
```bash
|
||||
paseo plugin logs workspace-plugin
|
||||
paseo plugin logs workspace-plugin --json
|
||||
```
|
||||
|
||||
The log tail includes `[paseo]` loading, ready, stopping, and stopped entries, plus compilation and
|
||||
load failures. It survives reloads and crashes. Inspect it when a plugin fails to start or an RPC
|
||||
rejects. See [Debug backend output](/docs/plugins/v0.7/reference#debug-backend-output) for retention and
|
||||
security behavior.
|
||||
|
||||
## Next
|
||||
|
||||
- [Plugin reference](/docs/plugins/v0.7/reference), add daemon behavior, use the Paseo SDK, contribute themes and attachments, and manage lifecycle.
|
||||
- [TypeScript SDK](/docs/sdk), the workspace, agent, provider, and config API exposed inside plugins.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,271 @@
|
||||
---
|
||||
title: Plugin quickstart
|
||||
description: Build, install, share, and update a trusted Paseo plugin.
|
||||
nav: Paseo v0.8 — Preview
|
||||
order: 46
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Plugin quickstart
|
||||
|
||||
> **For the upcoming Paseo v0.8 release.** Use the [current v0.7 docs](/docs/plugins/v0.7)
|
||||
> unless you are preparing a plugin for v0.8.
|
||||
|
||||
> **Experimental:** The plugin API is still evolving, so expect breaking changes and updates to
|
||||
> your plugins as Paseo evolves. See the [plugin roadmap](https://github.com/getpaseo/paseo/labels/plugins)
|
||||
> for planned contribution surfaces.
|
||||
|
||||
A plugin is a TypeScript project installed into one Paseo daemon. It can add
|
||||
[surfaces and sidebar items](/docs/plugins/v0.8/reference#surfaces-and-sidebar-items),
|
||||
[workspace panels](/docs/plugins/v0.8/reference#workspace-panels),
|
||||
[Command Center items](/docs/plugins/v0.8/reference#command-center-items),
|
||||
[slash commands](/docs/plugins/v0.8/reference#slash-commands),
|
||||
[composer pills](/docs/plugins/v0.8/reference#composer-pills),
|
||||
[timeline items](/docs/plugins/v0.8/reference#timeline-items),
|
||||
[themes](/docs/plugins/v0.8/reference#contribute-a-theme),
|
||||
[attachment sources](/docs/plugins/v0.8/reference#add-a-composer-attachment-source), and
|
||||
[daemon-side RPCs](/docs/plugins/v0.8/reference#add-plugin-specific-backend-behavior). Client
|
||||
contributions run on every Paseo client connected to that daemon, including mobile.
|
||||
|
||||
This guide scaffolds a plugin, runs it, and adds a workspace panel to it.
|
||||
|
||||
## Create a plugin
|
||||
|
||||
Use an absolute path on the daemon machine:
|
||||
|
||||
```bash
|
||||
paseo plugin init /absolute/path/to/workspace-plugin
|
||||
cd /absolute/path/to/workspace-plugin
|
||||
npm install
|
||||
```
|
||||
|
||||
`init` writes a strict TypeScript project and does not run the package manager. `npm install` adds
|
||||
development dependencies for typechecking and tests only; Paseo supplies the plugin SDK, React,
|
||||
React Native, TanStack Query, and Zod at runtime.
|
||||
|
||||
The scaffold is a working plugin: a sidebar surface with a button that asks the daemon for a
|
||||
greeting through an RPC.
|
||||
|
||||
```text
|
||||
workspace-plugin/
|
||||
paseo-plugin.json # { "id": "workspace-plugin" }
|
||||
index.client.tsx # runs in the Paseo app
|
||||
index.server.ts # runs in a daemon subprocess
|
||||
client/greeting.tsx # the surface component
|
||||
client/web.ts # the only file allowed to touch browser APIs
|
||||
server/greeting.ts # the RPC handler
|
||||
shared/greeting.ts # the RPC contract, imported by both
|
||||
package.json
|
||||
tsconfig.json
|
||||
```
|
||||
|
||||
Each entry default-exports one function that registers contributions and returns a cleanup
|
||||
function. `index.client.tsx` registers the surface and the sidebar item that opens it:
|
||||
|
||||
```tsx
|
||||
import type { PluginClientContext } from "@getpaseo/plugin";
|
||||
import { GreetingSurface } from "./client/greeting";
|
||||
|
||||
export default function contribute(client: PluginClientContext) {
|
||||
client.addSurface("greeting", GreetingSurface);
|
||||
client.addSidebarItem({
|
||||
id: "greeting",
|
||||
title: "Greeting",
|
||||
icon: "MessageCircle",
|
||||
surface: "greeting",
|
||||
});
|
||||
return () => {};
|
||||
}
|
||||
```
|
||||
|
||||
`index.server.ts` registers the handler for the contract in `shared/greeting.ts`:
|
||||
|
||||
```ts
|
||||
import type { PluginServerContext } from "@getpaseo/plugin";
|
||||
import { createGreeting } from "./server/greeting";
|
||||
import { greetingRpc } from "./shared/greeting";
|
||||
|
||||
export default function contribute(server: PluginServerContext) {
|
||||
server.handle(greetingRpc, createGreeting);
|
||||
return () => {};
|
||||
}
|
||||
```
|
||||
|
||||
The directory is the boundary. Code under `client/` compiles only into the app bundle, code under
|
||||
`server/` only into the daemon bundle, and `shared/` into both. Importing across that line, adding
|
||||
a code file at the root, or importing a `node:` module from client code is a compile error. A
|
||||
plugin with no daemon-side work can omit `index.server.ts`; a plugin with no UI can omit
|
||||
`index.client.tsx`.
|
||||
|
||||
Client code runs on phones as well as in browsers. The project typechecks without the DOM library,
|
||||
so `document` and `window` are errors outside `client/web.ts`, which shows how to gate a browser
|
||||
API behind `Platform.OS` with a native fallback. See
|
||||
[Cross-platform rules](/docs/plugins/v0.8/reference#cross-platform-rules) before writing UI.
|
||||
|
||||
## Install and try it
|
||||
|
||||
Plugins are trusted, unsandboxed code: server code and Git preparation commands run with the daemon
|
||||
user's access on the daemon machine, and client code runs inside the Paseo app. Installing a plugin
|
||||
means you trust that codebase, its dependencies, and its future updates.
|
||||
|
||||
Turn on **Enable plugins** under **Settings → Plugins** on the daemon you are installing into. It is
|
||||
the global switch for every plugin on that daemon. It is also the root `pluginsEnabled` field in the
|
||||
daemon's `config.json`; after editing the file, apply it with `paseo reload --json`. An automated
|
||||
tool must read the current value and get your explicit permission before turning it on.
|
||||
|
||||
Then typecheck and install:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
paseo plugin install /absolute/path/to/workspace-plugin
|
||||
paseo plugin ls
|
||||
```
|
||||
|
||||
`paseo plugin ls` should report the plugin as `running`. Open Paseo, choose **Greeting** in the
|
||||
sidebar, and press **Create greeting**. The message comes back from the daemon subprocess through
|
||||
the RPC.
|
||||
|
||||
If the sidebar item is missing, check that **Enable plugins** is on, the plugin is `running`, and
|
||||
the client is viewing the host you installed into. `paseo plugin logs workspace-plugin` shows the
|
||||
daemon-side output, including load errors.
|
||||
|
||||
## Add a workspace panel
|
||||
|
||||
A workspace panel opens as a tab next to agents, terminals, and files. Create `client/overview.tsx`:
|
||||
|
||||
```tsx
|
||||
import { type PluginWorkspacePanelProps, useWorkspace } from "@getpaseo/plugin";
|
||||
import { useMemo } from "react";
|
||||
import { Text, View } from "react-native";
|
||||
|
||||
export function WorkspaceOverview({ theme, layout, workspaceId }: PluginWorkspacePanelProps) {
|
||||
const workspace = useWorkspace(workspaceId, ({ name, directory }) => ({
|
||||
name,
|
||||
directory,
|
||||
}));
|
||||
const styles = useMemo(
|
||||
() => ({
|
||||
screen: {
|
||||
flex: 1,
|
||||
padding: layout.compact ? 16 : 24,
|
||||
gap: layout.compact ? 8 : 12,
|
||||
backgroundColor: theme.colors.surface0,
|
||||
},
|
||||
title: { color: theme.colors.foreground, fontSize: layout.compact ? 20 : 24 },
|
||||
label: { color: theme.colors.foregroundMuted },
|
||||
detail: { color: theme.colors.foreground },
|
||||
}),
|
||||
[theme, layout.compact],
|
||||
);
|
||||
|
||||
return (
|
||||
<View style={styles.screen}>
|
||||
<Text style={styles.title}>{workspace?.name}</Text>
|
||||
<Text style={styles.label}>Directory</Text>
|
||||
<Text style={styles.detail}>{workspace?.directory}</Text>
|
||||
</View>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
`useWorkspace` reads the fields the panel renders from the app's cached state, without an RPC and
|
||||
without re-rendering when unrelated fields change. Every `Text` takes its color from
|
||||
`theme.colors`, and `layout.compact` drives spacing, so the panel works in every Paseo theme and on
|
||||
phones. See [Theme and layout](/docs/plugins/v0.8/reference#theme-and-layout) for the token list.
|
||||
|
||||
Register the panel and a Command Center item that opens it by adding to `index.client.tsx`:
|
||||
|
||||
```tsx
|
||||
import { WorkspaceOverview } from "./client/overview";
|
||||
|
||||
// Inside contribute(client), after the existing registrations:
|
||||
client.addWorkspacePanel({
|
||||
id: "overview",
|
||||
title: "Workspace overview",
|
||||
icon: "PanelsTopLeft",
|
||||
context: "workspace",
|
||||
locations: ["workspace", "explorer"],
|
||||
Component: WorkspaceOverview,
|
||||
});
|
||||
client.addCommandCenterItem({
|
||||
id: "open-overview",
|
||||
title: "Open workspace overview",
|
||||
icon: "PanelsTopLeft",
|
||||
context: "workspace",
|
||||
onSelect({ openPanel }) {
|
||||
openPanel("overview");
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
`icon` is a [Lucide](https://lucide.dev/icons/) icon name.
|
||||
|
||||
## Edit and reload
|
||||
|
||||
Source changes take effect only when you reload the plugin:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
paseo plugin reload workspace-plugin
|
||||
```
|
||||
|
||||
A reload stops the old plugin, runs its cleanup, compiles the current source, and starts it again.
|
||||
A failed reload stays failed and reports its error in `paseo plugin ls`; fix the source and reload
|
||||
again.
|
||||
|
||||
Open a workspace, press **⌘K** on macOS or **Ctrl+K** on Windows and Linux, and choose **Open
|
||||
workspace overview**. The panel opens as a workspace tab.
|
||||
|
||||
## Install a published plugin
|
||||
|
||||
Plugins published in a Git repository install by shorthand or URL:
|
||||
|
||||
```bash
|
||||
paseo plugin add owner/repository
|
||||
paseo plugin add https://gitlab.com/group/repository.git
|
||||
paseo plugin add owner/monorepo:plugins/workspace
|
||||
paseo plugin add owner/repository --ref main
|
||||
```
|
||||
|
||||
Append `:relative/path` when the plugin lives below the repository root. Without `--ref`, the
|
||||
default branch is tracked; a branch tracks updates, while a tag or commit stays pinned.
|
||||
|
||||
```bash
|
||||
paseo plugin status
|
||||
paseo plugin update workspace-plugin
|
||||
paseo plugin update --all
|
||||
```
|
||||
|
||||
Paseo compiles TypeScript itself, so most plugins need no build step. A repository that must
|
||||
install a dependency Paseo does not provide, or generate files, declares
|
||||
[`build` commands](/docs/plugins/v0.8/reference#cli-reference) in its manifest.
|
||||
|
||||
## Read backend logs
|
||||
|
||||
Daemon-side handlers and cleanup can use normal Node logging:
|
||||
|
||||
```ts
|
||||
console.log("Refreshing issues");
|
||||
console.error("Issue refresh failed", error);
|
||||
```
|
||||
|
||||
Read the recent output from **Settings → Plugins → Logs** or the CLI:
|
||||
|
||||
```bash
|
||||
paseo plugin logs workspace-plugin
|
||||
paseo plugin logs workspace-plugin --json
|
||||
```
|
||||
|
||||
The tail includes `[paseo]` loading, ready, stopping, and stopped entries, plus compilation and load
|
||||
failures, and it survives reloads and crashes. Client-side output stays in the app. See
|
||||
[Debug backend output](/docs/plugins/v0.8/reference#debug-backend-output) for retention and what not to
|
||||
log.
|
||||
|
||||
## Next
|
||||
|
||||
- [Plugin reference](/docs/plugins/v0.8/reference): every contribution type, its fields, the runtime
|
||||
modules, hosts, and the CLI.
|
||||
- [Migrate a plugin to runtime entries](/docs/plugins/v0.8/migration): move a plugin written against the
|
||||
single `index.ts` entry, step by step.
|
||||
- [TypeScript SDK](/docs/sdk): the workspace, agent, provider, and config API available as `paseo`
|
||||
in client and server code.
|
||||
@@ -2,12 +2,14 @@
|
||||
title: Migrate a plugin to runtime entries
|
||||
description: Mechanical migration from a mixed plugin entry to explicit client and server entries.
|
||||
nav: Migration
|
||||
order: 47
|
||||
order: 48
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Migrate a plugin to runtime entries
|
||||
|
||||
> **For the upcoming Paseo v0.8 release.** This migration is not required for Paseo v0.7.
|
||||
|
||||
Give this page to a coding agent with the plugin directory as its working directory. Execute the
|
||||
steps in order. Do not keep a compatibility entry.
|
||||
|
||||
@@ -2,13 +2,15 @@
|
||||
title: Plugin reference
|
||||
description: Local plugin files, client and server runtimes, platform limits, contributions, RPCs, lifecycle, hosts, and CLI commands.
|
||||
nav: Reference
|
||||
order: 46
|
||||
order: 47
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Plugin reference
|
||||
|
||||
Migrating an existing plugin? Follow the standalone [runtime-entry migration guide](/docs/plugins/migration).
|
||||
> **For the upcoming Paseo v0.8 release.** Return to the [v0.8 quickstart](/docs/plugins/v0.8).
|
||||
|
||||
Migrating an existing plugin? Follow the standalone [runtime-entry migration guide](/docs/plugins/v0.8/migration).
|
||||
|
||||
Local plugins are directory sources installed into one Paseo daemon. A plugin can contribute:
|
||||
|
||||
@@ -52,7 +54,7 @@ The required root manifest is `paseo-plugin.json`. It contains the default plugi
|
||||
| `index.server.ts` | Daemon subprocess | `PluginServerContext` | When the plugin handles RPCs |
|
||||
|
||||
At least one entry is required; both accept `.ts` or `.tsx`. A directory that still has only the
|
||||
old `index.ts` fails to load and points at the [migration guide](/docs/plugins/migration).
|
||||
old `index.ts` fails to load and points at the [migration guide](/docs/plugins/v0.8/migration).
|
||||
|
||||
Plugin, surface, sidebar-item, workspace-panel, Command Center item, attachment-source, and
|
||||
slash-command IDs start with a lowercase letter and contain lowercase letters, numbers, or hyphens.
|
||||
@@ -1068,7 +1070,7 @@ Use `paseo plugin ls` to read the current status and error.
|
||||
|
||||
| Symptom | Check |
|
||||
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Plugin entry split is required` | The directory has only an `index.ts` entry. Follow the [migration guide](/docs/plugins/migration). |
|
||||
| `Plugin entry split is required` | The directory has only an `index.ts` entry. Follow the [migration guide](/docs/plugins/v0.8/migration). |
|
||||
| `Plugin entry points are missing` | Neither `index.client.tsx` nor `index.server.ts` exists with that exact name. |
|
||||
| `server-only module cannot be imported into the plugin client bundle` | Client code imports `server/` or a `*.server.*` file. Move the work behind an RPC and import its contract from `shared/`. |
|
||||
| `client-only module cannot be imported into the plugin server bundle` | Server code imports `client/` or a `*.client.*` file. Register that contribution from `index.client.tsx` instead. |
|
||||
@@ -14,7 +14,7 @@ Build or manage the requested plugin directly. Use the current public docs to ca
|
||||
Fetch [https://paseo.sh/llms.txt](https://paseo.sh/llms.txt) first. Select and fetch the current plugin Markdown pages from that index before changing a plugin:
|
||||
|
||||
- [Plugin quickstart](https://paseo.sh/docs/plugins.md) ([browser page](https://paseo.sh/docs/plugins))
|
||||
- [Plugin reference](https://paseo.sh/docs/plugins/reference.md) ([browser page](https://paseo.sh/docs/plugins/reference))
|
||||
- [Plugin reference](https://paseo.sh/docs/plugins/v0.8/reference.md) ([browser page](https://paseo.sh/docs/plugins/v0.8/reference))
|
||||
|
||||
Use the deployed docs when they disagree with this skill. Do not send the user away to read them instead of completing the work.
|
||||
|
||||
@@ -598,7 +598,7 @@ Use `--host <url>` when managing a daemon other than the CLI default. A Git sour
|
||||
|
||||
Do not restart the daemon to load source changes. Restarting it can kill the agent performing the work.
|
||||
|
||||
For an old mixed entry, follow the standalone [runtime-entry migration guide](https://paseo.sh/docs/plugins/migration.md) mechanically.
|
||||
For an old mixed entry, follow the standalone [v0.8 runtime-entry migration guide](https://paseo.sh/docs/plugins/v0.8/migration) mechanically.
|
||||
|
||||
## Verify the outcome
|
||||
|
||||
|
||||
Reference in New Issue
Block a user