mirror of
https://github.com/getpaseo/paseo.git
synced 2026-11-06 08:24:46 +00:00
docs(plugins): consolidate guides and document npm publishing
This commit is contained in:
Mohamed Boudra
@@ -52,7 +52,7 @@ app:
|
||||
sdk:
|
||||
- "packages/plugin/**"
|
||||
- "plugin-examples/**"
|
||||
- "public-docs/plugins/v0.8/**"
|
||||
- "public-docs/plugins/**"
|
||||
- "packages/client/**"
|
||||
- "packages/highlight/**"
|
||||
- "packages/protocol/**"
|
||||
|
||||
@@ -50,10 +50,9 @@ Run agents in parallel on your own machines. Ship from your phone or your desk.
|
||||
## Plugins
|
||||
|
||||
Add themes, workspace panels, commands, settings screens, and coding-agent providers with trusted
|
||||
TypeScript plugins. Install from a local directory or Git repository with `paseo plugin add <source>`.
|
||||
TypeScript plugins. Install from npm, Git, or a local directory with `paseo plugin install <source>`.
|
||||
|
||||
See the [plugin docs](https://paseo.sh/docs/plugins) for your Paseo version, or start with the
|
||||
[0.8 beta quickstart](https://paseo.sh/docs/plugins/v0.8). Plugins run with access to your daemon
|
||||
Start with the [plugin quickstart](https://paseo.sh/docs/plugins). Plugins run with access to your daemon
|
||||
machine and inside connected clients; install only code you trust.
|
||||
|
||||
## Getting Started
|
||||
|
||||
+15
-15
@@ -68,7 +68,7 @@ runtime modules, so consumers do not install these packages when adding the plug
|
||||
```
|
||||
|
||||
Declare the supported Paseo range and keep it current when adopting newer APIs. See the
|
||||
[requirements contract](../public-docs/plugins/v0.8/reference.md#requirements), including legacy
|
||||
[requirements contract](../public-docs/plugins/reference.md#requirements), including legacy
|
||||
manifests and prerelease matching.
|
||||
|
||||
The config key is the runtime plugin ID. The manifest ID is the default selected during install;
|
||||
@@ -109,8 +109,8 @@ Removing a Git source deletes Paseo's managed checkout.
|
||||
|
||||
## Managed source ownership
|
||||
|
||||
The [public source reference](../public-docs/plugins/v0.8/reference.md#plugin-sources) owns identifier
|
||||
syntax, npm prerequisites, and publishing instructions. Both clients send the source unchanged
|
||||
The [public source reference](../public-docs/plugins/reference.md#plugin-sources) owns identifier
|
||||
syntax and npm prerequisites; the [publishing guide](../public-docs/plugins/publishing.md) owns distribution. Both clients send the source unchanged
|
||||
through `installPluginSource`; only the daemon resolves host paths and acquires sources.
|
||||
|
||||
`ManagedPluginSources` owns acquisition and offline source description. Config stores the active
|
||||
@@ -188,10 +188,10 @@ Shared files import contract helpers and types from `@getpaseo/plugin`. Server h
|
||||
set; an unknown name renders nothing so it cannot break the plugin surface.
|
||||
Its controlled modal keeps presentation metadata on `<Modal title="…" icon={…}>` and body UI in
|
||||
`<Modal.Content>`. Body layout, sheet-aware scrolling, and clipboard actions follow the
|
||||
[host UI contract](../public-docs/plugins/v0.8/reference.md#host-ui).
|
||||
[host UI contract](../public-docs/plugins/reference.md#host-ui).
|
||||
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/v0.8/reference.md`.
|
||||
See `public-docs/plugins/reference.md`.
|
||||
|
||||
### SDK import boundaries
|
||||
|
||||
@@ -232,7 +232,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/v0.8/reference.md#works-on-mobile) for the complete
|
||||
[public plugin reference](../public-docs/plugins/reference.md#works-on-mobile) for the complete
|
||||
pattern.
|
||||
|
||||
```ts
|
||||
@@ -282,7 +282,7 @@ Use plugin RPC for plugin-specific backend behavior that is not a normal Paseo o
|
||||
Host-targeted clients and discovery are owned by `packages/app/src/plugins/hosts`, with per-installation
|
||||
bindings supplied by the bundle loader. Bind the imperative getter to that installation; do not
|
||||
resolve ownership through a mutable current-plugin global. Keep observation ownership in this module
|
||||
and transport ownership in the app host runtime. See the [public host API contract](../public-docs/plugins/v0.8/reference.md#discover-hosts-and-target-another-host).
|
||||
and transport ownership in the app host runtime. See the [public host API contract](../public-docs/plugins/reference.md#discover-hosts-and-target-another-host).
|
||||
|
||||
Each subprocess gets an exclusively owned `plugin:<id>` session. That identity is reserved from
|
||||
normal clients, never resumes another session, and is cleaned immediately on exit without reconnect
|
||||
@@ -292,7 +292,7 @@ catalog is complete.
|
||||
|
||||
When the same plugin contribution exists on multiple hosts, Paseo shows it once in the sidebar and
|
||||
adds a host picker to the screen header. The selected host supplies the bundle, RPC transport, and
|
||||
query cache. Explicit SDK targets follow the [host API contract](../public-docs/plugins/v0.8/reference.md#discover-hosts-and-target-another-host).
|
||||
query cache. Explicit SDK targets follow the [host API contract](../public-docs/plugins/reference.md#discover-hosts-and-target-another-host).
|
||||
|
||||
Workspace panels, Command Center items, and client slash commands are client contributions. The
|
||||
daemon transports their compiled bundle without interpreting placement or callbacks. Panel props
|
||||
@@ -311,14 +311,14 @@ existing agent-context instances, but it cannot create an agent panel without an
|
||||
Command Center callbacks use the selected host's existing `PaseoApi` for normal Paseo operations.
|
||||
They use typed plugin RPC only for plugin-specific backend work. Surface and panel navigation
|
||||
belongs to the app; plugins do not receive Expo Router or workspace-layout store access.
|
||||
See the public [navigation fields](../public-docs/plugins/v0.8/reference.md#surfaces-and-sidebar-items)
|
||||
and [external links and workspace browsers](../public-docs/plugins/v0.8/reference.md#external-links-and-workspace-browsers)
|
||||
See the public [navigation fields](../public-docs/plugins/reference.md#surfaces-and-sidebar-items)
|
||||
and [external links and workspace browsers](../public-docs/plugins/reference.md#external-links-and-workspace-browsers)
|
||||
for the author-facing contract.
|
||||
|
||||
## Lifecycle hooks
|
||||
|
||||
Server entries register lifecycle observers with `server.on()` and request transforms with
|
||||
`server.before()`. The [public reference](../public-docs/plugins/v0.8/reference.md#lifecycle-hooks)
|
||||
`server.before()`. The [public reference](../public-docs/plugins/reference.md#lifecycle-hooks)
|
||||
owns callback shapes, ordering, and failure behavior. `plugin-examples/lifecycle-logger` registers all
|
||||
eleven hooks; `plugin-examples/lifecycle-actions` demonstrates common automation callbacks.
|
||||
|
||||
@@ -366,7 +366,7 @@ and `plugin-examples/provider-acp-transformer`.
|
||||
Provider-emitted plugin timeline items use the same renderer registration as transformed and
|
||||
daemon-appended plugin items. The direct example includes both sides. The renderer-only
|
||||
`plugin-examples/inline-thinking` example shows that timeline presentation remains independent of a
|
||||
provider implementation. The public [provider plugin guide](../public-docs/plugins/v0.8/providers.md)
|
||||
provider implementation. The public [provider plugin guide](../public-docs/plugins/providers.md)
|
||||
owns author workflow, lifecycle, testing, and distribution guidance.
|
||||
|
||||
`ProviderRegistration.icon` is a file path relative to the plugin directory, such as `icon.svg`.
|
||||
@@ -379,7 +379,7 @@ SVG or URL.
|
||||
## Contribute buttons
|
||||
|
||||
Header buttons and composer pills share the client-only descriptor and registration lifecycle in
|
||||
`packages/app/src/plugins/buttons/`. The [public button reference](../public-docs/plugins/v0.8/reference.md#header-buttons)
|
||||
`packages/app/src/plugins/buttons/`. The [public button reference](../public-docs/plugins/reference.md#header-buttons)
|
||||
owns the author API and placement rules. Keep presentation policy in this module so another
|
||||
placement can reuse behavior without copying registration or action state.
|
||||
|
||||
@@ -503,7 +503,7 @@ drops the optional presentation fields.
|
||||
|
||||
Register ordinary components with `client.addSettingsScreen` and open them with `openSettings`.
|
||||
The host settings shell owns navigation and layout; plugin content must not add another page
|
||||
scroll view or header. See the [author contract](../public-docs/plugins/v0.8/reference.md#settings-screens)
|
||||
scroll view or header. See the [author contract](../public-docs/plugins/reference.md#settings-screens)
|
||||
and `plugin-examples/settings` for the named UI components and persistence API.
|
||||
|
||||
Settings storage is scoped to the runtime installation ID, never the source path or manifest ID.
|
||||
@@ -538,7 +538,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 [v0.8 runtime-entry migration guide](../public-docs/plugins/v0.8/migration.md).
|
||||
Existing plugin authors should follow the standalone [v0.8 runtime-entry migration guide](../public-docs/plugins/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
|
||||
|
||||
@@ -210,7 +210,7 @@ async function expectPluginSourceDocsOpen(page: Page): Promise<void> {
|
||||
await page.getByRole("link", { name: "Docs", exact: true }).click();
|
||||
const docsPage = await docsPagePromise;
|
||||
try {
|
||||
await docsPage.waitForURL("https://paseo.sh/docs/plugins/v0.8/reference#plugin-sources", {
|
||||
await docsPage.waitForURL("https://paseo.sh/docs/plugins/reference#plugin-sources", {
|
||||
waitUntil: "commit",
|
||||
});
|
||||
} finally {
|
||||
|
||||
@@ -71,7 +71,7 @@ it("rejects catalogs without requirements from pre-0.8 daemons", () => {
|
||||
result.installCatalog("host", [{ id: "example", clientBundle }], { client });
|
||||
expect(starts()).toBe(0);
|
||||
expect(result.getEvaluationError("host", "example")).toContain(
|
||||
"https://paseo.sh/docs/plugins/v0.8/migration",
|
||||
"https://paseo.sh/docs/plugins/migration",
|
||||
);
|
||||
});
|
||||
|
||||
|
||||
@@ -33,7 +33,7 @@ import { settingsStyles } from "@/styles/settings";
|
||||
import { confirmDialog } from "@/utils/confirm-dialog";
|
||||
|
||||
const pluginQueryKey = (serverId: string) => ["plugins", serverId] as const;
|
||||
const PLUGIN_SOURCE_DOCS_URL = "https://paseo.sh/docs/plugins/v0.8/reference#plugin-sources";
|
||||
const PLUGIN_SOURCE_DOCS_URL = "https://paseo.sh/docs/plugins/reference#plugin-sources";
|
||||
type PluginRowAction = "reload" | "enable" | "disable" | "remove";
|
||||
|
||||
function errorMessage(error: unknown): string {
|
||||
|
||||
@@ -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/v0.8/migration.md", import.meta.url)),
|
||||
fileURLToPath(new URL("../../../public-docs/plugins/migration.md", import.meta.url)),
|
||||
"utf8",
|
||||
);
|
||||
const table = migration.slice(
|
||||
|
||||
@@ -33,7 +33,7 @@ export function assertPluginCompatibility(input: PluginCompatibilityInput): void
|
||||
if (satisfies(version, range) || satisfies(stableCore, range)) return;
|
||||
const action =
|
||||
input.requirements?.paseo === undefined
|
||||
? "This plugin has no requirements.paseo and targets Paseo before 0.8. Ask its author to migrate it: https://paseo.sh/docs/plugins/v0.8/migration"
|
||||
? "This plugin has no requirements.paseo and targets Paseo before 0.8. Ask its author to migrate it: https://paseo.sh/docs/plugins/migration"
|
||||
: `Use a compatible plugin version or update the ${input.runtime}.`;
|
||||
throw new Error(
|
||||
`Plugin "${input.id}" requires Paseo ${range}. Your ${input.runtime} is ${input.version}. ${action}`,
|
||||
|
||||
@@ -1015,7 +1015,7 @@ export default function contribute(plugin: unknown) {
|
||||
"Plugin entry points are missing",
|
||||
);
|
||||
await expect(service.installDirectory({ path: legacy })).rejects.toThrow(
|
||||
"This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/v0.8/migration",
|
||||
"This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/migration",
|
||||
);
|
||||
await expect(service.installDirectory({ path: startupFailure })).rejects.toThrow(
|
||||
"startup exploded",
|
||||
@@ -1025,7 +1025,7 @@ export default function contribute(plugin: unknown) {
|
||||
id: "legacy-plugin",
|
||||
status: "failed",
|
||||
error:
|
||||
"This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/v0.8/migration",
|
||||
"This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/migration",
|
||||
}),
|
||||
expect.objectContaining({
|
||||
id: "missing-entry",
|
||||
|
||||
@@ -80,7 +80,7 @@ it("marks pre-0.8 plugins failed on startup and recovers after migration and rel
|
||||
expect(await service.listPlugins()).toEqual([
|
||||
expect.objectContaining({
|
||||
status: "failed",
|
||||
error: expect.stringContaining("https://paseo.sh/docs/plugins/v0.8/migration"),
|
||||
error: expect.stringContaining("https://paseo.sh/docs/plugins/migration"),
|
||||
}),
|
||||
]);
|
||||
await writePlugin(root, ">=0.8.0");
|
||||
@@ -97,7 +97,7 @@ it("still requires entry migration when an old plugin adds a compatible requirem
|
||||
await writeFile(path.join(root, "index.ts"), "export default () => () => {};");
|
||||
const { service } = await host();
|
||||
await expect(service.installDirectory({ path: root })).rejects.toThrow(
|
||||
"https://paseo.sh/docs/plugins/v0.8/migration",
|
||||
"https://paseo.sh/docs/plugins/migration",
|
||||
);
|
||||
});
|
||||
|
||||
|
||||
@@ -1422,7 +1422,7 @@ export default function contribute(server: { registerProvider(provider: Provider
|
||||
const runtime = createTestRuntime();
|
||||
|
||||
await expect(runtime.startPlugin("legacy", directory)).rejects.toThrow(
|
||||
"This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/v0.8/migration",
|
||||
"This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/migration",
|
||||
);
|
||||
});
|
||||
|
||||
|
||||
@@ -276,7 +276,7 @@ async function resolveEntryPaths(directory: string): Promise<{
|
||||
const legacyEntry = await findEntry(directory, ["index.ts", "index.tsx"]);
|
||||
if (legacyEntry) {
|
||||
throw new Error(
|
||||
"This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/v0.8/migration",
|
||||
"This plugin was made for an older version of Paseo and cannot run on Paseo v0.8. Ask its author to update it. Plugin authors can follow the migration guide: https://paseo.sh/docs/plugins/migration",
|
||||
);
|
||||
}
|
||||
throw new Error(
|
||||
|
||||
@@ -157,15 +157,15 @@ 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];
|
||||
const match =
|
||||
/^\/docs\/plugins\/v0\.[78](?:(\.md)|\/(index|reference|providers|migration)(\.md)?)?\/?$/.exec(
|
||||
pathname,
|
||||
);
|
||||
if (!match) return undefined;
|
||||
const page = match[2] && match[2] !== "index" ? `/${match[2]}` : "";
|
||||
const extension = match[1] || match[3] ? ".md" : "";
|
||||
return `/docs/plugins${page}${extension}`;
|
||||
}
|
||||
|
||||
function formatLabel(segment: string): string {
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { buildDocsNavTree, getDocs, getLegacyDocsRedirect } from "./docs";
|
||||
import { buildDocsNavTree, getDoc, getDocs, getLegacyDocsRedirect } from "./docs";
|
||||
|
||||
describe("versioned plugin documentation", () => {
|
||||
it("keeps stable and beta releases together in the Plugins navigation", () => {
|
||||
describe("plugin documentation", () => {
|
||||
it("groups current guides by task without version navigation", () => {
|
||||
const plugins = buildDocsNavTree(getDocs()).find(
|
||||
(node) => node.type === "category" && node.label === "Plugins",
|
||||
);
|
||||
@@ -10,35 +10,32 @@ describe("versioned plugin documentation", () => {
|
||||
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 — Beta",
|
||||
href: "/docs/plugins/v0.8",
|
||||
children: [
|
||||
{ type: "page", label: "Provider plugins", href: "/docs/plugins/v0.8/providers" },
|
||||
{ type: "page", label: "Migration", href: "/docs/plugins/v0.8/migration" },
|
||||
{ type: "page", label: "Reference", href: "/docs/plugins/v0.8/reference" },
|
||||
],
|
||||
},
|
||||
{ type: "page", label: "Quickstart", href: "/docs/plugins" },
|
||||
{ type: "page", label: "Publishing", href: "/docs/plugins/publishing" },
|
||||
{ type: "page", label: "Provider plugins", href: "/docs/plugins/providers" },
|
||||
{ type: "page", label: "Migration", href: "/docs/plugins/migration" },
|
||||
{ type: "page", label: "Reference", href: "/docs/plugins/reference" },
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
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",
|
||||
);
|
||||
it.each(["v0.7", "v0.8"])("redirects %s links to existing current pages", (version) => {
|
||||
for (const page of ["", "/index", "/reference", "/providers", "/migration"]) {
|
||||
const target = `/docs/plugins${page === "/index" ? "" : page}`;
|
||||
expect(getDoc(target.slice("/docs/".length))).toBeDefined();
|
||||
for (const extension of ["", ".md"]) {
|
||||
const source = `/docs/plugins/${version}${page}${extension}`;
|
||||
expect(getLegacyDocsRedirect(source)).toBe(`${target}${extension}`);
|
||||
expect(getLegacyDocsRedirect(`${source}/`)).toBe(`${target}${extension}`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
it("serves canonical pages without redirect loops", () => {
|
||||
for (const page of ["", "/publishing", "/reference", "/providers", "/migration"]) {
|
||||
expect(getLegacyDocsRedirect(`/docs/plugins${page}`)).toBeUndefined();
|
||||
expect(getLegacyDocsRedirect(`/docs/plugins${page}.md`)).toBeUndefined();
|
||||
}
|
||||
expect(getLegacyDocsRedirect("/docs/plugins/v0.8/unknown")).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -20,7 +20,7 @@ The callback receives the request after earlier plugins have transformed it. The
|
||||
preserve their settings; the explicit values replace only the named fields. Paseo validates and saves
|
||||
the resulting configuration before starting the agent. Existing agents are unchanged.
|
||||
|
||||
See the [lifecycle reference](../../public-docs/plugins/v0.8/reference.md#lifecycle-hooks) for ordering
|
||||
See the [lifecycle reference](../../public-docs/plugins/reference.md#lifecycle-hooks) for ordering
|
||||
and callback shapes. [Lifecycle actions](../lifecycle-actions) demonstrates provider switching and
|
||||
environment injection. Its provider-switch callback clears provider options when changing Codex to
|
||||
Claude, so use these examples separately when trying the Codex-specific settings.
|
||||
|
||||
@@ -24,8 +24,8 @@ The example contributes one header button at a time. Additional actions live und
|
||||
|
||||
The client entry owns the active example. [client/examples.tsx](client/examples.tsx) contains the
|
||||
descriptors, updates, and React content. Return `.remove()` cleanup when the example moves or stops.
|
||||
See the [button reference](../../public-docs/plugins/v0.8/reference.md#button-descriptor) and
|
||||
[composer migration](../../public-docs/plugins/v0.8/migration.md#composer-pills).
|
||||
See the [button reference](../../public-docs/plugins/reference.md#button-descriptor) and
|
||||
[composer migration](../../public-docs/plugins/migration.md#composer-pills).
|
||||
|
||||
From the repository root, `npm run typecheck --workspace=@getpaseo/plugin` checks this example
|
||||
against the SDK. Existing plugin projects must update `@getpaseo/plugin` before running their own
|
||||
|
||||
@@ -33,4 +33,4 @@ Claude agent.
|
||||
See [agent configuration](../agent-configuration) for a focused example that injects MCP servers and
|
||||
changes Codex sandbox and approval options while preserving other settings.
|
||||
|
||||
See the [lifecycle reference](../../public-docs/plugins/v0.8/reference.md#lifecycle-hooks) for the API.
|
||||
See the [lifecycle reference](../../public-docs/plugins/reference.md#lifecycle-hooks) for the API.
|
||||
|
||||
@@ -15,7 +15,7 @@ The same entries appear in the target daemon's `daemon.log`. The plugin log view
|
||||
tail; use the daemon log for longer captures. Log lines are capped at 16 KiB, so a large timeline can
|
||||
be truncated.
|
||||
|
||||
See the [lifecycle reference](../../public-docs/plugins/v0.8/reference.md#lifecycle-hooks) for callback
|
||||
See the [lifecycle reference](../../public-docs/plugins/reference.md#lifecycle-hooks) for callback
|
||||
shapes and delivery rules. The real-provider test in
|
||||
`packages/server/src/server/plugins/lifecycle.real.e2e.test.ts` runs both examples on an isolated daemon
|
||||
and saves evidence under `.dev/lifecycle-proof/`.
|
||||
|
||||
@@ -18,12 +18,12 @@ The package ships the existing TypeScript entry and client sources. Paseo compil
|
||||
its directory plugin loader; no package build or preparation command is required. React,
|
||||
React Native, and `@getpaseo/plugin` are peer contracts supplied by the host. npm is needed for
|
||||
installation, not loading or reloading. You can also install this directory while developing.
|
||||
See the [source reference](https://paseo.sh/docs/plugins/v0.8/reference#plugin-sources)
|
||||
See the [source reference](https://paseo.sh/docs/plugins/reference#plugin-sources)
|
||||
for supported identifiers and preparation rules.
|
||||
|
||||
The examples demonstrate default and custom padding, a full-width body, author-owned ScrollView and
|
||||
FlatList scrolling, horizontal tabs, and clipboard actions with a keyboard-aware input. See the
|
||||
[host UI reference](https://paseo.sh/docs/plugins/v0.8/reference#host-ui) for the API contract.
|
||||
[host UI reference](https://paseo.sh/docs/plugins/reference#host-ui) for the API contract.
|
||||
|
||||
The browser regression installs this exact example in an isolated daemon:
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"name": "@getpaseo/plugin-example-modal-ui",
|
||||
"version": "0.1.1",
|
||||
"description": "Interactive Paseo plugin example for modal forms, scrolling, and clipboard actions",
|
||||
"homepage": "https://paseo.sh/docs/plugins/v0.8",
|
||||
"homepage": "https://paseo.sh/docs/plugins",
|
||||
"license": "Apache-2.0",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
|
||||
+1
-1
@@ -187,7 +187,7 @@ GitHub shorthand checks an existing host directory first. Append `:<directory>`
|
||||
monorepo. `paseo plugin ls [id]` does not contact the remote. `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/v0.7/reference) for installation, trust, lifecycle, and log-retention
|
||||
[Plugin reference](/docs/plugins/reference) for installation, trust, lifecycle, and log-retention
|
||||
behavior.
|
||||
|
||||
## Listing agents
|
||||
|
||||
+289
-11
@@ -1,21 +1,299 @@
|
||||
---
|
||||
title: Paseo plugin documentation
|
||||
description: Choose the plugin API documentation for your Paseo release.
|
||||
nav: Versions
|
||||
title: Plugin quickstart
|
||||
description: Build, install, share, and update a trusted Paseo plugin.
|
||||
nav: Quickstart
|
||||
order: 44
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Paseo plugin documentation
|
||||
# Plugin quickstart
|
||||
|
||||
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). It can also
|
||||
[connect a coding agent as a provider](/docs/plugins/providers). 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 — Beta](/docs/plugins/v0.8)
|
||||
Use an absolute path on the daemon machine:
|
||||
|
||||
Build plugins for Paseo 0.8 beta, with separate client and server entries. Existing plugin authors should
|
||||
follow the [v0.8 migration guide](/docs/plugins/v0.8/migration).
|
||||
```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 # plugin ID and supported Paseo versions
|
||||
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/client";
|
||||
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/server";
|
||||
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 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
|
||||
```
|
||||
|
||||
Or install the directory from the app:
|
||||
|
||||
1. Open **Settings → Plugins** on the target host.
|
||||
2. Paste `/absolute/path/to/workspace-plugin` into **Plugin source**.
|
||||
3. Select **Install plugin**. The app uses the plugin ID from `paseo-plugin.json`.
|
||||
|
||||
The source field also accepts Git repositories, npm packages, and plugin subdirectories. See
|
||||
[Plugin sources](/docs/plugins/reference#plugin-sources) for the accepted syntax and resolution
|
||||
rules. If the form asks you to update the host, update that host before installing; the existing
|
||||
management actions remain available.
|
||||
|
||||
Each installed plugin row shows its status and description. Use its switch to enable or disable it,
|
||||
and open its three-dot menu for settings, logs, reload, and removal.
|
||||
|
||||
`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/client";
|
||||
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
|
||||
|
||||
Install a trusted npm plugin using npm on the daemon host:
|
||||
|
||||
```bash
|
||||
paseo plugin install npm:@acme/paseo-review@1.2.0
|
||||
```
|
||||
|
||||
Or paste the same identifier into **Settings → Plugins → Plugin source** and select **Install
|
||||
plugin**. The installed row uses the manifest ID and provides the same enable switch, Logs, Reload,
|
||||
and Remove actions as a directory plugin. npm is needed for acquisition; subsequent loading and
|
||||
reload use the installed files.
|
||||
|
||||
See [plugin sources](/docs/plugins/reference#plugin-sources) for identifier syntax. To share your own plugin, follow
|
||||
[Publish a plugin](/docs/plugins/publishing).
|
||||
|
||||
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. `--ref` selects the initial
|
||||
Git content once; omitting it installs the default HEAD. See the [source reference](/docs/plugins/reference#plugin-sources) for exact syntax.
|
||||
|
||||
```bash
|
||||
paseo plugin ls
|
||||
paseo plugin update workspace-plugin
|
||||
paseo plugin update --all
|
||||
```
|
||||
|
||||
`ls` reports source identity and the current installed revision without contacting the remote.
|
||||
`update` shows a proposed npm or Git revision and asks for approval. npm offers a newer latest
|
||||
release; Git offers the current default HEAD, regardless of the initial install selector.
|
||||
Use `--check` to preview only or `--yes` to approve without a prompt.
|
||||
See the [CLI reference](/docs/plugins/reference#cli-reference) for explicit targets and bulk updates.
|
||||
|
||||
## 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 by opening the plugin's three-dot menu under **Settings → Plugins** and
|
||||
selecting **Logs**, or use 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
|
||||
|
||||
- [Publish a plugin](/docs/plugins/publishing): share through npm, a private registry, or Git.
|
||||
- [Build a provider plugin](/docs/plugins/providers): connect an agent directly or through ACP,
|
||||
render provider-owned timeline items, test it, and publish it.
|
||||
- [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.
|
||||
|
||||
@@ -2,13 +2,13 @@
|
||||
title: Migrate a plugin to runtime entries
|
||||
description: Mechanical migration from a mixed plugin entry to explicit client and server entries.
|
||||
nav: Migration
|
||||
order: 48
|
||||
order: 47
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Migrate a plugin to runtime entries
|
||||
|
||||
> **For Paseo v0.8 beta.** This migration is not required for Paseo v0.7.
|
||||
Use this guide to update plugins written for Paseo 0.7 or earlier to the current client/server entry format, introduced in 0.8.
|
||||
|
||||
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.
|
||||
@@ -285,12 +285,11 @@ After migrating the entries and imports, add the minimum runtime version to `pas
|
||||
}
|
||||
```
|
||||
|
||||
Keep your existing ID and build commands. Missing `requirements.paseo` means `<0.8.0`, so Paseo 0.8
|
||||
rejects the plugin even if its files have been moved. Adding the field alone does not migrate the
|
||||
Keep your existing ID and build commands. Missing `requirements.paseo` means `<0.8.0`, so Paseo 0.8 and later
|
||||
reject the plugin even if its files have been moved. Adding the field alone does not migrate the
|
||||
code. Update the local `@getpaseo/plugin` development dependency to the version you target and
|
||||
reinstall dependencies before typechecking.
|
||||
|
||||
For a 0.8 beta, use its explicit version in the SDK dependency and `>=0.8.0` in the manifest.
|
||||
See [requirements](reference#requirements) for range and prerelease semantics.
|
||||
|
||||
## 8. Verify the migration
|
||||
@@ -2,18 +2,16 @@
|
||||
title: Build a provider plugin
|
||||
description: Add a coding agent to Paseo directly or adapt an ACP agent.
|
||||
nav: Provider plugins
|
||||
order: 47
|
||||
order: 46
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Build a provider plugin
|
||||
|
||||
> **For Paseo v0.8 beta.** Start with the
|
||||
> [plugin quickstart](/docs/plugins/v0.8) if you have not built a Paseo plugin before.
|
||||
Start with the [plugin quickstart](/docs/plugins) if you have not built a Paseo plugin before.
|
||||
|
||||
A provider plugin connects a coding agent to Paseo without adding it to Paseo core. Publish the
|
||||
plugin in a Git repository and users can install and update it with `paseo plugin add` and
|
||||
`paseo plugin update`.
|
||||
A provider plugin connects a coding agent to Paseo without adding it to Paseo core. [Publish the plugin](/docs/plugins/publishing) on npm or in a Git repository so users can
|
||||
install it with `paseo plugin install`.
|
||||
|
||||
Choose one implementation path:
|
||||
|
||||
@@ -398,15 +396,8 @@ Test the provider against the real agent, not only mocked frames:
|
||||
5. render every custom timeline item on desktop and mobile-width layouts;
|
||||
6. reload and remove the plugin while a session is active and confirm the session terminates.
|
||||
|
||||
Push the plugin to a Git repository. Users install it with:
|
||||
Follow [Publish a plugin](/docs/plugins/publishing) to distribute the provider through npm or Git.
|
||||
Keep agent compatibility and releases in the plugin project.
|
||||
|
||||
```bash
|
||||
paseo plugin add owner/repository
|
||||
paseo plugin update my-provider-plugin
|
||||
```
|
||||
|
||||
Keep vendor compatibility and releases in that repository. Paseo core should only change when the
|
||||
provider boundary cannot express a user-facing capability shared by more than one provider.
|
||||
|
||||
See the [plugin reference](/docs/plugins/v0.8/reference#providers) for the exact runtime and SVG
|
||||
See the [plugin reference](/docs/plugins/reference#providers) for the exact runtime and SVG
|
||||
rules.
|
||||
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Publish a plugin
|
||||
description: Share a Paseo plugin on npm, through a private registry, or from a Git repository.
|
||||
nav: Publishing
|
||||
order: 45
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Publish a plugin
|
||||
|
||||
Publish your plugin on npm so users can install it and its dependencies with one source identifier.
|
||||
Start with a working [plugin project](/docs/plugins). npm is required on the daemon host for installation;
|
||||
loading and reloading the installed plugin use its local files.
|
||||
|
||||
## Publish on npm
|
||||
|
||||
Give your `package.json` a unique package name and version, and include the plugin files in the
|
||||
published package. For a plugin with both client and server entries, add these fields to the
|
||||
scaffold's existing `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@acme/paseo-review",
|
||||
"version": "1.0.0",
|
||||
"private": false,
|
||||
"files": [
|
||||
"paseo-plugin.json",
|
||||
"index.client.tsx",
|
||||
"index.server.ts",
|
||||
"client/",
|
||||
"server/",
|
||||
"shared/"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The scaffold sets `private: true`; change it to `false` to allow publication.
|
||||
Replace `@acme` with your npm scope. Match the entry filenames to your project, and include any
|
||||
additional assets your plugin reads. Keep the scaffold's development dependencies and scripts.
|
||||
The package name identifies the npm source; `paseo-plugin.json` supplies the installed plugin ID.
|
||||
|
||||
From the plugin directory, check and publish:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm pack --dry-run
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
Inspect the pack output for the manifest, entries, imported files, and assets before publishing.
|
||||
Then test the published package through Paseo:
|
||||
|
||||
```bash
|
||||
paseo plugin install npm:@acme/paseo-review@1.0.0
|
||||
```
|
||||
|
||||
Users can paste `npm:@acme/paseo-review` into **Settings → Plugins → Plugin source** to install the
|
||||
latest release. An explicit version selects that installation; it does not pin future updates.
|
||||
See [source identifiers](/docs/plugins/reference#plugin-sources) for tags, ranges, and subdirectories.
|
||||
|
||||
### Dependencies and generated files
|
||||
|
||||
Put libraries your plugin needs at runtime in `dependencies`. Paseo uses npm to install those
|
||||
libraries and their transitive dependencies. Development dependencies are omitted and automatic
|
||||
peer dependency installation is disabled. Keep Paseo's host modules—the plugin SDK, React, React
|
||||
Native, TanStack Query, and Zod—in `devDependencies` for authoring; Paseo supplies their runtime
|
||||
instances. Declare other required peer modules as dependencies.
|
||||
|
||||
Paseo compiles TypeScript and bundles imports separately for the client and server. You do not need
|
||||
to precompile or bundle an ordinary TypeScript plugin. The entry names remain `index.client.ts`
|
||||
or `.tsx` and `index.server.ts` or `.tsx`; at least one is required. npm's `main` and `exports`
|
||||
fields do not select Paseo entries.
|
||||
|
||||
If your plugin generates code or assets, generate them before publishing and include the output
|
||||
in `files`. Prebuilt JavaScript can live under `client/`, `server/`, or `shared/`, imported by the
|
||||
normal TypeScript entry. Preserve the [runtime boundaries](/docs/plugins/reference#project-files)
|
||||
and host module imports. Paseo still compiles the entries.
|
||||
|
||||
npm lifecycle scripts, including dependency `install`, `postinstall`, and `prepare` scripts, do not
|
||||
run when Paseo acquires a package. Publish ready-to-use files where possible. If installation needs
|
||||
host-specific preparation, such as rebuilding a native dependency, declare it in the manifest's
|
||||
[`build` commands](/docs/plugins/reference#cli-reference). These commands run on installation and
|
||||
update after the Paseo requirements check. An npm plugin does not need a build command to install
|
||||
its ordinary dependencies.
|
||||
|
||||
## Use a private GitHub package
|
||||
|
||||
Paseo uses the daemon user's npm configuration and environment for registries and authentication.
|
||||
For a company plugin, publish a scoped package such as `@acme/paseo-review` to GitHub Packages.
|
||||
Add the repository and publication registry to its `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@acme/paseo-review",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/acme/paseo-review.git"
|
||||
},
|
||||
"publishConfig": {
|
||||
"registry": "https://npm.pkg.github.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Authenticate with GitHub Packages and run `npm publish` from the plugin directory. Follow
|
||||
[GitHub's npm registry guide](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
|
||||
for publishing credentials and package access permissions.
|
||||
|
||||
To install the private package, configure npm **on the daemon host, as the user running Paseo**.
|
||||
Add the scope mapping to that user's `~/.npmrc`:
|
||||
|
||||
```ini
|
||||
@acme:registry=https://npm.pkg.github.com
|
||||
```
|
||||
|
||||
Log in with a GitHub personal access token (classic) with `read:packages` and access to the package:
|
||||
|
||||
```bash
|
||||
npm login --scope=@acme --auth-type=legacy --registry=https://npm.pkg.github.com
|
||||
paseo plugin install npm:@acme/paseo-review
|
||||
```
|
||||
|
||||
Use your GitHub username and the token as the password. Keep credentials on the daemon host;
|
||||
enter only the source identifier in the app. Updates use the host's current npm configuration too.
|
||||
Other npm-compatible registries use the same npm configuration mechanism.
|
||||
|
||||
## Share through GitHub or Git
|
||||
|
||||
You can also share a repository containing the plugin project:
|
||||
|
||||
```bash
|
||||
paseo plugin install github:acme/paseo-review
|
||||
paseo plugin install git:https://git.example.com/acme/paseo-review.git
|
||||
```
|
||||
|
||||
For a plugin that only imports host modules, no preparation is needed. If it has runtime npm
|
||||
dependencies, commit `package.json` and `package-lock.json`, then add this to `paseo-plugin.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "paseo-review",
|
||||
"requirements": { "paseo": ">=0.8.0" },
|
||||
"build": [["npm", "ci", "--omit=dev"]]
|
||||
}
|
||||
```
|
||||
|
||||
`npm ci` installs from the committed lockfile and fails if it disagrees with `package.json`.
|
||||
`--omit=dev` leaves authoring tools out of the installation. Paseo runs the command in the plugin
|
||||
directory on the daemon host, where npm must be on `PATH`. Git installation does not infer this
|
||||
command from the presence of a package file.
|
||||
|
||||
If additional preparation needs development tools, `--omit=dev` will not install those tools.
|
||||
Prefer generating and publishing the required files on npm. If you distribute the same project on
|
||||
npm and Git, omit the dependency-install build command from the published manifest: npm acquisition
|
||||
already installs production dependencies.
|
||||
|
||||
Set `requirements.paseo` to the earliest release whose APIs your plugin uses. `>=0.8.0` permits
|
||||
compatible later releases, including 0.9; add an upper bound only for a known incompatibility.
|
||||
See [requirements](/docs/plugins/reference#requirements).
|
||||
@@ -8,9 +8,9 @@ category: Plugins
|
||||
|
||||
# Plugin reference
|
||||
|
||||
> **For Paseo v0.8 beta.** Return to the [v0.8 quickstart](/docs/plugins/v0.8).
|
||||
Start with the [plugin quickstart](/docs/plugins) to create your first plugin.
|
||||
|
||||
Migrating an existing plugin? Follow the standalone [runtime-entry migration guide](/docs/plugins/v0.8/migration).
|
||||
Migrating an existing plugin? Follow the standalone [runtime-entry migration guide](/docs/plugins/migration).
|
||||
|
||||
Local plugins are directory sources installed into one Paseo daemon. A plugin can contribute:
|
||||
|
||||
@@ -78,8 +78,8 @@ Prerelease Paseo versions also satisfy a range their stable core (`major.minor.p
|
||||
for typechecking. Raise the minimum when adopting a newer API. Add an upper bound when a later
|
||||
release is incompatible; a minimum alone does not promise protection from future breaking changes.
|
||||
|
||||
The daemon checks its version before installing, running Git build commands, or loading a plugin,
|
||||
and checks again on startup, enable, and reload. A rejected Git update keeps the installed revision.
|
||||
The daemon checks its version before installing, running preparation commands, or loading a plugin,
|
||||
and checks again on startup, enable, and reload. A rejected update keeps the installed revision.
|
||||
Each connected app checks its own version before evaluating client code and shows incompatibility
|
||||
in Settings → Plugins. A compatible daemon does not make an older app compatible. A plugin with no
|
||||
client entry does not require the connected app to match.
|
||||
@@ -96,7 +96,7 @@ and cannot show this new diagnostic.
|
||||
| `index.server.ts` | Daemon subprocess | `PluginServerContext` | When the plugin contributes handlers, hooks, settings persistence, or providers |
|
||||
|
||||
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/v0.8/migration).
|
||||
old `index.ts` fails to load and points at the [migration guide](/docs/plugins/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.
|
||||
@@ -275,7 +275,7 @@ process, credential, and other machine-local work under `server/`. A plugin with
|
||||
|
||||
### Providers
|
||||
|
||||
Follow [Build a provider plugin](/docs/plugins/v0.8/providers) for direct and ACP implementations,
|
||||
Follow [Build a provider plugin](/docs/plugins/providers) for direct and ACP implementations,
|
||||
session lifecycle, composer settings, timeline renderers, testing, and distribution.
|
||||
|
||||
Call `server.registerProvider()` with a `ProviderRegistration` from
|
||||
@@ -1959,24 +1959,8 @@ keeps the complete dependency tree and `package-lock.json` when activating it. T
|
||||
package and lockfile provide its current version and artifact integrity. A version, tag, or range
|
||||
chooses content for this installation only.
|
||||
|
||||
Publish the existing [plugin project format](#project-files): `paseo-plugin.json`, at least one
|
||||
`index.server.ts` or `index.client.tsx` entry (either accepts `.ts` or `.tsx`), and every imported
|
||||
file and asset under the appropriate `server/`, `client/`, or `shared/` directory. npm's `main` and
|
||||
`exports` fields do not select Paseo entry points. Use the package's `files` list to include those
|
||||
files and inspect `npm pack --dry-run` before publishing.
|
||||
|
||||
- Put non-host runtime dependencies in `dependencies`. npm installs their transitive dependencies.
|
||||
- Keep the SDK, React, React Native, TanStack Query, and Zod in `devDependencies` for authoring;
|
||||
Paseo supplies their runtime instances. Development dependencies are not installed for consumers,
|
||||
and npm peer auto-installation is disabled. List required non-host peer modules as dependencies.
|
||||
- Package lifecycle scripts (`install`, `postinstall`, `prepare`, and dependency scripts) do not run
|
||||
during acquisition. Declare required installation preparation in the plugin manifest's
|
||||
[`build` argv commands](#cli-reference). Those commands run after the Paseo requirements check.
|
||||
A native dependency that requires rebuilding needs an explicit preparation command.
|
||||
- Prefer publishing ready-to-use files. Prebuilt JavaScript belongs under its runtime directory,
|
||||
imported by the normal TypeScript entry. Preserve host module imports and runtime boundaries;
|
||||
Paseo still validates and compiles the entries. A package containing only `dist/index.js` is not
|
||||
a Paseo plugin.
|
||||
For package contents, dependencies, preparation, and private registries, see
|
||||
[Publish a plugin](/docs/plugins/publishing).
|
||||
|
||||
A failed download, dependency installation, manifest check, preparation command, compilation, or
|
||||
activation discards the candidate. Other installed plugins keep running. Removing an npm plugin
|
||||
@@ -2043,10 +2027,7 @@ step:
|
||||
{
|
||||
"id": "review",
|
||||
"requirements": { "paseo": ">=0.8.0" },
|
||||
"build": [
|
||||
["npm", "ci"],
|
||||
["npm", "run", "build"]
|
||||
]
|
||||
"build": [["npm", "ci", "--omit=dev"]]
|
||||
}
|
||||
```
|
||||
|
||||
@@ -2070,7 +2051,7 @@ Use `paseo plugin ls` to read the current status and error.
|
||||
|
||||
| Symptom | Check |
|
||||
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `This plugin was made for an older version of Paseo` | The directory has only an `index.ts` entry. Follow the [migration guide](/docs/plugins/v0.8/migration). |
|
||||
| `This plugin was made for an older version of Paseo` | The directory has only an `index.ts` entry. Follow the [migration guide](/docs/plugins/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/`. 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/`. Register that contribution from `index.client.tsx` instead. |
|
||||
@@ -1,203 +0,0 @@
|
||||
---
|
||||
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. Apply updates with:
|
||||
|
||||
```bash
|
||||
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
@@ -1,309 +0,0 @@
|
||||
---
|
||||
title: Plugin quickstart
|
||||
description: Build, install, share, and update a trusted Paseo plugin.
|
||||
nav: Paseo v0.8 — Beta
|
||||
order: 46
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Plugin quickstart
|
||||
|
||||
> **For Paseo v0.8 beta.** Use the [v0.7 docs](/docs/plugins/v0.7)
|
||||
> if you run the stable release.
|
||||
|
||||
> **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). It can also
|
||||
[connect a coding agent as a provider](/docs/plugins/v0.8/providers). 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 # plugin ID and supported Paseo versions
|
||||
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/client";
|
||||
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/server";
|
||||
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 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
|
||||
```
|
||||
|
||||
Or install the directory from the app:
|
||||
|
||||
1. Open **Settings → Plugins** on the target host.
|
||||
2. Paste `/absolute/path/to/workspace-plugin` into **Plugin source**.
|
||||
3. Select **Install plugin**. The app uses the plugin ID from `paseo-plugin.json`.
|
||||
|
||||
The source field also accepts Git repositories, npm packages, and plugin subdirectories. See
|
||||
[Plugin sources](/docs/plugins/v0.8/reference#plugin-sources) for the accepted syntax and resolution
|
||||
rules. If the form asks you to update the host, update that host before installing; the existing
|
||||
management actions remain available.
|
||||
|
||||
Each installed plugin row shows its status and description. Use its switch to enable or disable it,
|
||||
and open its three-dot menu for settings, logs, reload, and removal.
|
||||
|
||||
`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/client";
|
||||
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
|
||||
|
||||
Install a trusted npm plugin using npm on the daemon host:
|
||||
|
||||
```bash
|
||||
paseo plugin install npm:@acme/paseo-review@1.2.0
|
||||
```
|
||||
|
||||
Or paste the same identifier into **Settings → Plugins → Plugin source** and select **Install
|
||||
plugin**. The installed row uses the manifest ID and provides the same enable switch, Logs, Reload,
|
||||
and Remove actions as a directory plugin. npm is needed for acquisition; subsequent loading and
|
||||
reload use the installed files.
|
||||
|
||||
See [plugin sources](/docs/plugins/v0.8/reference#plugin-sources) for exact identifiers, registry
|
||||
configuration, dependencies, and what authors must publish.
|
||||
|
||||
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. `--ref` selects the initial
|
||||
Git content once; omitting it installs the default HEAD. See the [source reference](/docs/plugins/v0.8/reference#plugin-sources) for exact syntax.
|
||||
|
||||
```bash
|
||||
paseo plugin ls
|
||||
paseo plugin update workspace-plugin
|
||||
paseo plugin update --all
|
||||
```
|
||||
|
||||
`ls` reports source identity and the current installed revision without contacting the remote.
|
||||
`update` shows a proposed npm or Git revision and asks for approval. npm offers a newer latest
|
||||
release; Git offers the current default HEAD, regardless of the initial install selector.
|
||||
Use `--check` to preview only or `--yes` to approve without a prompt.
|
||||
See the [CLI reference](/docs/plugins/v0.8/reference#cli-reference) for explicit targets and bulk updates.
|
||||
|
||||
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 by opening the plugin's three-dot menu under **Settings → Plugins** and
|
||||
selecting **Logs**, or use 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
|
||||
|
||||
- [Build a provider plugin](/docs/plugins/v0.8/providers): connect an agent directly or through ACP,
|
||||
render provider-owned timeline items, test it, and publish it.
|
||||
- [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.
|
||||
@@ -172,7 +172,7 @@ test("PR routing declares stable behavior ownership", () => {
|
||||
sdk: [
|
||||
"packages/plugin/**",
|
||||
"plugin-examples/**",
|
||||
"public-docs/plugins/v0.8/**",
|
||||
"public-docs/plugins/**",
|
||||
"packages/client/**",
|
||||
"packages/highlight/**",
|
||||
"packages/protocol/**",
|
||||
|
||||
@@ -14,11 +14,12 @@ 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/v0.8/reference.md) ([browser page](https://paseo.sh/docs/plugins/v0.8/reference))
|
||||
- [Publishing](https://paseo.sh/docs/plugins/publishing.md): npm package contents, dependencies, Git preparation, and private registries.
|
||||
- [Plugin reference](https://paseo.sh/docs/plugins/reference.md) ([browser page](https://paseo.sh/docs/plugins/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.
|
||||
|
||||
In the Paseo repository, use `public-docs/plugins/v0.8/reference.md` for the checkout's API, including
|
||||
In the Paseo repository, use `public-docs/plugins/reference.md` for the checkout's API, including
|
||||
unreleased changes. Use `docs/plugins.md` for maintainer guidance. Complete contracts belong in the
|
||||
public docs; this skill indexes the references and examples.
|
||||
|
||||
@@ -38,8 +39,8 @@ Pick the contribution that matches the request. Each row names the registration,
|
||||
| Attachment source | `client.addAttachmentSource` + `server.handle` | Let the user attach a searchable external resource, such as an issue, to a prompt | reference.md → Add a composer attachment source; `plugin-examples/linear` |
|
||||
| Theme | `addTheme` | A light or dark palette under Settings → Appearance | reference.md → Contribute a theme; `plugin-examples/catppuccin` |
|
||||
| Plugin RPC | `defineRpc` + `server.handle` + `useRpc` | Daemon-side work that is not a normal Paseo operation: vendor APIs, credentials, local files | reference.md → Add plugin-specific backend behavior |
|
||||
| Lifecycle events | `server.on` | Observe agent/workspace lifecycle, inspect ended turns, and answer permission requests | [Lifecycle hooks](https://paseo.sh/docs/plugins/v0.8/reference.md#lifecycle-hooks) |
|
||||
| Creation and launch hooks | `server.before` | Change agent config, provider options, MCP servers, environment, or workspace isolation before the operation | [Before hooks](https://paseo.sh/docs/plugins/v0.8/reference.md#before-hooks) |
|
||||
| Lifecycle events | `server.on` | Observe agent/workspace lifecycle, inspect ended turns, and answer permission requests | [Lifecycle hooks](https://paseo.sh/docs/plugins/reference.md#lifecycle-hooks) |
|
||||
| Creation and launch hooks | `server.before` | Change agent config, provider options, MCP servers, environment, or workspace isolation before the operation | [Before hooks](https://paseo.sh/docs/plugins/reference.md#before-hooks) |
|
||||
| Paseo SDK | `usePaseo()` / handler `{ paseo }` | Normal Paseo operations: workspaces, agents, providers, config | reference.md → Use the Paseo SDK |
|
||||
|
||||
| Lifecycle task | Example |
|
||||
@@ -83,7 +84,7 @@ by the CLI version. Raise the minimum when adopting newer APIs; add an upper bou
|
||||
Paseo release is incompatible. Use npm semver ranges and explicitly include beta versions when
|
||||
targeting betas. Missing requirements mean `<0.8.0`; complete the 0.8 entry migration before adding
|
||||
`>=0.8.0`. Verify compatibility with both the daemon and the app running client contributions.
|
||||
See [requirements](https://paseo.sh/docs/plugins/v0.8/reference#requirements).
|
||||
See [requirements](https://paseo.sh/docs/plugins/reference#requirements).
|
||||
|
||||
Each runtime has its own optional entry. A plugin must have at least one. Both entries accept
|
||||
`.ts` or `.tsx`; use `.tsx` when an entry imports components.
|
||||
@@ -245,7 +246,7 @@ export default function contribute(client: PluginClientContext) {
|
||||
Icons are Lucide icon names. `theme` is a typed `PluginTheme` on every surface and panel. Primary text uses `theme.colors.foreground`; labels use `theme.colors.foregroundMuted`; the root view uses `theme.colors.surface0`. `layout.compact` is true on mobile and narrow windows. Paseo owns the route, header, host picker, close action, error boundary, and per-installation query client.
|
||||
|
||||
Before writing imports, classify each module as shared, client, or server. Follow the
|
||||
[SDK import boundaries](https://paseo.sh/docs/plugins/v0.8/reference.md#runtime-modules), including
|
||||
[SDK import boundaries](https://paseo.sh/docs/plugins/reference.md#runtime-modules), including
|
||||
transitive and type dependencies. The root is shared-only; hooks and client contexts belong to
|
||||
`@getpaseo/plugin/client`, server contexts to `/server`, and host UI to `/client/react-native` or `/client/ui`.
|
||||
Install dependencies locally for typechecking; Paseo supplies host runtime modules. JSX uses the
|
||||
@@ -592,15 +593,16 @@ When the same sidebar contribution exists on several connected hosts, Paseo show
|
||||
|
||||
## Typecheck and manage
|
||||
|
||||
Always typecheck before install or reload:
|
||||
When editing a plugin, typecheck its source before install or reload:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
paseo plugin install /absolute/path/to/plugin
|
||||
paseo plugin install /absolute/path/to/plugin --id another-runtime-id
|
||||
paseo plugin add owner/repository # Git source; append :path for a monorepo subdirectory
|
||||
paseo plugin add owner/repository --ref main # branches track, tags and commits pin
|
||||
paseo plugin status
|
||||
paseo plugin install npm:@acme/paseo-review
|
||||
paseo plugin install npm:@acme/paseo-review@1.2.0
|
||||
paseo plugin install github:owner/repository
|
||||
paseo plugin install github:owner/repository --ref main
|
||||
paseo plugin update my-plugin
|
||||
paseo plugin ls
|
||||
paseo plugin reload my-plugin
|
||||
@@ -610,11 +612,16 @@ paseo plugin enable my-plugin
|
||||
paseo plugin remove my-plugin
|
||||
```
|
||||
|
||||
Use `--host <url>` when managing a daemon other than the CLI default. A Git source that must install or generate something declares `build` in `paseo-plugin.json` as a list of argv arrays; Paseo runs them without a shell on install and update and keeps the old version if one fails. Plugin source edits require `paseo plugin reload`; config changes to the global switch require `paseo reload`. A failed plugin reload stays failed; inspect `paseo plugin ls` for the load error and `paseo plugin logs <id>` for subprocess output, fix the source, typecheck, and reload again. `remove` deletes configuration, never the source directory.
|
||||
For npm, ensure npm is on the daemon's `PATH`; use that host's registry configuration and credentials. Install selectors choose
|
||||
content once; they do not pin updates. `install` and `add` are aliases. Follow the
|
||||
[publishing guide](https://paseo.sh/docs/plugins/publishing.md) for Paseo's package contents and
|
||||
preparation requirements; standard npm publishing commands apply.
|
||||
|
||||
Use `--host <url>` when managing a daemon other than the CLI default. A Git source that must install or generate something declares `build` in `paseo-plugin.json` as a list of argv arrays; Paseo runs them without a shell on install and update and keeps the old version if one fails. Plugin source edits require `paseo plugin reload`; config changes to the global switch require `paseo reload`. A failed plugin reload stays failed; inspect `paseo plugin ls` for the load error and `paseo plugin logs <id>` for subprocess output, fix the source, typecheck, and reload again. `remove` keeps local source directories and deletes managed Git/npm installations.
|
||||
|
||||
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 [v0.8 runtime-entry migration guide](https://paseo.sh/docs/plugins/v0.8/migration) mechanically.
|
||||
For an old mixed entry, follow the standalone [runtime-entry migration guide](https://paseo.sh/docs/plugins/migration) mechanically.
|
||||
|
||||
## Verify the outcome
|
||||
|
||||
|
||||
Reference in New Issue
Block a user