puter/paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-11-04 23:44:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

Let Git plugins prepare themselves during installation (#4158)

Browse Source 
* feat(plugins): support prepared Git installations

Let Git plugins declare explicit preparation commands without making package installation the default. Keep installation transactional, make plugin trust explicit, and use one canonical source reference for monorepos.

* fix(plugins): parse Windows source references
This commit is contained in:
Mohamed Boudra
2026-09-01 16:12:23 +02:00
committed by GitHub
parent 0c38749c38
commit 07125d2c02
21 changed files with 604 additions and 434 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plugins.md
+38 -15
View File
@@ -2,8 +2,9 @@
Local plugins contribute daemon RPCs, native app surfaces, workspace panels, Command Center items,
composer pills, app themes, and composer attachment sources from one `index.ts`. Paseo executes the server contribution in a
subprocess and evaluates the client contribution in the app runtime. Plugin code is trusted code;
Paseo does not sandbox it.
subprocess and evaluates the client contribution in the app runtime.
> **Trust every plugin you add.** `paseo plugin add` and `paseo plugin install` mean “I trust this codebase.” Plugins are unsandboxed: server code and Git preparation commands run with the daemon user's access on the daemon host, and client contributions run inside Paseo. The repository's dependencies and future updates are part of that trust decision. With `--host`, preparation runs on that remote daemon host.
## Install a directory source
@@ -47,15 +48,13 @@ my-plugin/
paseo-plugin.json
index.ts
main.client.tsx
paseo-plugin.d.ts
package.json
tsconfig.json
```
Paseo compiles TypeScript and TSX when loading the plugin, so these packages are development dependencies only.
The generated declaration file supplies `@getpaseo/plugin` and `@getpaseo/plugin/server` types until the
SDK is distributed as a public package. Regenerate new plugins with the matching Paseo CLI when the
SDK contract changes.
The generated `package.json` installs `@getpaseo/plugin` and the other host modules as development
dependencies for local typechecking and tests. Paseo compiles TypeScript and TSX and supplies the
runtime modules, so consumers do not install these packages when adding the plugin.
```json
{
@@ -84,28 +83,52 @@ directory always wins over shorthand resolution.
```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 --path plugins/review
paseo plugin add owner/monorepo:plugins/review
paseo plugin add owner/repository --ref main
paseo plugin status
paseo plugin update review
paseo plugin update --all
```
Append `:relative/path` to the source when the plugin lives below the repository root.
Omitting `--ref` tracks the remote's default branch. A branch passed with `--ref` also tracks;
tags and commits stay pinned. `status` fetches tracked refs and reports the installed and available
commits. `update` checks out a new version, validates its manifest, compiles both bundles, and starts
it before changing the configured path. A compilation or startup failure restores the running
version. Removing a Git source deletes Paseo's managed checkout.
commits. Removing a Git source deletes Paseo's managed checkout.
Git installation does not run a package manager or install script. A distributable source plugin
uses Paseo's host-provided modules or commits any other bundled source it needs. Native React Native
dependencies work only when the Paseo app already ships the native module.
### Declare Git preparation
Most plugins should omit `build`. Use it only when the staged checkout must install a dependency
that Paseo does not provide, generate source or assets, or perform another required preparation
step:
```json
{
"id": "review",
"build": [
["npm", "ci"],
["npm", "run", "build"]
]
}
```
`build` is an optional list of argv arrays. Each array must contain at least one non-empty string;
shell command strings are rejected. Paseo starts the executable directly, without a shell, from the
plugin directory in the staged checkout. It never detects lockfiles or chooses a package manager.
On install and every update, Paseo resolves the exact Git revision and manifest, runs the declared
commands, then validates, compiles, and activates the candidate. It logs each argv command and its
output in the daemon log. If a command fails, the error includes its output, Paseo discards the
candidate, and the existing installed and running version stays untouched. On a remote daemon, all
of this happens on the remote daemon host.
Server contributions can write to stdout and stderr with normal Node logging. Paseo adds `[paseo]`
entries for loading, ready, stopping, and stopped transitions. Compilation and load failures are
recorded as stderr entries before a subprocess exists. Inspect the recent in-memory
tail from the host plugin settings or with `paseo plugin logs <id>`. Reload, disable, and process
tail from the host plugin settings or with `paseo plugin logs <id>`. Git preparation commands are
recorded in `$PASEO_HOME/daemon.log` before a plugin exists, rather than the plugin log tail. Reload, disable, and process
failure retain the tail; removing the plugin clears it. Daemon restarts do not retain the tail, but
structured copies remain in `$PASEO_HOME/daemon.log`. Plugin output can contain secrets, so do not
log credentials or tokens.
packages/cli/src/commands/plugin/index.test.ts
+72 -2
View File
@@ -9,25 +9,44 @@ const getPluginLogs = vi.fn(async () => [
message: "ready",
},
]);
const installDirectoryPlugin = vi.fn(async () => ({
id: "trusted-plugin",
path: "/plugins/trusted-plugin",
enabled: true,
status: "running" as const,
}));
const installPluginSource = vi.fn(async () => ({
id: "trusted-plugin",
path: "/plugins/trusted-plugin",
enabled: true,
status: "running" as const,
}));
const close = vi.fn(async () => undefined);
const features: { pluginManagement?: boolean; pluginLogs?: boolean } = {};
const features: {
pluginManagement?: boolean;
pluginLogs?: boolean;
pluginGitManagement?: boolean;
} = {};
vi.mock("../../utils/client.js", () => ({
connectToDaemon: vi.fn(async () => ({
getLastServerInfoMessage: () => ({ features }),
listPlugins,
getPluginLogs,
installDirectoryPlugin,
installPluginSource,
close,
})),
}));
import { render } from "../../output/index.js";
import { runPluginListCommand, runPluginLogsCommand } from "./index.js";
import { createPluginCommand, runPluginListCommand, runPluginLogsCommand } from "./index.js";
describe("plugin management commands", () => {
beforeEach(() => {
features.pluginManagement = false;
features.pluginLogs = false;
features.pluginGitManagement = false;
vi.clearAllMocks();
});
@@ -63,4 +82,55 @@ describe("plugin management commands", () => {
},
]);
});
it("makes trust explicit at the plugin add entry point", () => {
const command = createPluginCommand();
expect(
command.commands.find((subcommand) => subcommand.name() === "install")?.description(),
).toContain("Trust and install");
expect(command.helpInformation()).toContain("trusted, unsandboxed plugins");
});
it("prints the trust acknowledgement before installing", async () => {
features.pluginManagement = true;
const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
const command = createPluginCommand();
await command.parseAsync(["install", "/plugins/trusted-plugin"], { from: "user" });
expect(stderr).toHaveBeenCalledWith(
expect.stringContaining("Git build commands run unsandboxed on the daemon host"),
);
expect(installDirectoryPlugin).toHaveBeenCalledWith("/plugins/trusted-plugin", undefined);
stderr.mockRestore();
});
it("folds the legacy --path option into the plugin source reference", async () => {
features.pluginGitManagement = true;
const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
const command = createPluginCommand();
await command.parseAsync(["install", "owner/monorepo", "--path", "plugins/review"], {
from: "user",
});
expect(installPluginSource).toHaveBeenCalledWith({
source: "owner/monorepo:plugins/review",
});
stderr.mockRestore();
});
it("keeps an absolute monorepo path as one plugin source reference", async () => {
features.pluginGitManagement = true;
const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
const command = createPluginCommand();
await command.parseAsync(["install", "/plugins/monorepo:plugins/review"], { from: "user" });
expect(installPluginSource).toHaveBeenCalledWith({
source: "/plugins/monorepo:plugins/review",
});
expect(installDirectoryPlugin).not.toHaveBeenCalled();
stderr.mockRestore();
});
});
packages/cli/src/commands/plugin/index.ts
+16 -7
View File
@@ -6,6 +6,10 @@ import type {
PluginSourceStatusItem,
PluginSourceUpdateItem,
} from "@getpaseo/protocol/messages";
import {
formatPluginSourceReference,
parsePluginSourceReference,
} from "@getpaseo/protocol/plugin-source-reference";
import type { CommandOptions, ListResult, OutputSchema, SingleResult } from "../../output/index.js";
import { withOutput } from "../../output/index.js";
import { addJsonAndDaemonHostOptions, addJsonOption } from "../../utils/command-options.js";
@@ -113,6 +117,9 @@ async function install(
options: PluginOptions,
_command: Command,
): Promise<SingleResult<PluginListItem>> {
process.stderr.write(
"Trusting plugin code: server code and Git build commands run unsandboxed on the daemon host; client code runs inside Paseo. Dependencies and future updates are part of the codebase you trust.\n",
);
const isExplicitPath =
path.isAbsolute(source) ||
source === "." ||
@@ -121,17 +128,19 @@ async function install(
source.startsWith("../") ||
source.startsWith(".\\") ||
source.startsWith("..\\");
const canUseLegacyDirectoryInstall = isExplicitPath && !options.ref && !options.path;
const hasPluginPathSuffix = parsePluginSourceReference(source).pluginPath !== undefined;
const canUseLegacyDirectoryInstall =
isExplicitPath && !hasPluginPathSuffix && !options.ref && !options.path;
const sourceReference = formatPluginSourceReference(source, options.path);
const data = canUseLegacyDirectoryInstall
? await withPluginManagementClient(options.host, (client) =>
client.installDirectoryPlugin(source, options.id),
)
: await withPluginSourceClient(options.host, (client) =>
client.installPluginSource({
source,
source: sourceReference,
...(options.id ? { id: options.id } : {}),
...(options.ref ? { ref: options.ref } : {}),
...(options.path ? { pluginPath: options.path } : {}),
}),
);
return { type: "single", data, schema: pluginSchema };
@@ -188,7 +197,7 @@ async function remove(
}
export function createPluginCommand(): Command {
const plugin = new Command("plugin").description("Manage trusted plugins");
const plugin = new Command("plugin").description("Manage trusted, unsandboxed plugins");
addJsonOption(
plugin
.command("init")
@@ -206,11 +215,11 @@ export function createPluginCommand(): Command {
plugin
.command("install")
.alias("add")
.description("Install a plugin from a directory or Git repository")
.argument("<source>", "Host directory, owner/repo shorthand, or Git URL")
.description("Trust and install a plugin from a directory or Git repository")
.argument("<source>", "Host directory, Git source, or Git source:plugin/path")
.option("--id <id>", "Runtime plugin ID (defaults to paseo-plugin.json id)")
.option("--ref <ref>", "Git branch, tag, or commit")
.option("--path <path>", "Plugin directory within the repository"),
.option("--path <path>", "Legacy form of the :plugin/path source suffix"),
).action(withOutput(install));
addJsonAndDaemonHostOptions(
plugin.command("status").description("Check plugin source updates").argument("[id]"),
packages/cli/src/commands/plugin/scaffold.test.ts
+17 -1
View File
@@ -1,4 +1,4 @@
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
import path from "node:path";
import { tmpdir } from "node:os";
import ts from "typescript";
@@ -34,6 +34,22 @@ describe("plugin scaffold", () => {
expect(JSON.parse(await readFile(path.join(directory, "paseo-plugin.json"), "utf8"))).toEqual({
id: "hello-plugin",
});
expect(JSON.parse(await readFile(path.join(directory, "package.json"), "utf8"))).toEqual({
name: "hello-plugin",
private: true,
version: "0.0.0",
scripts: { typecheck: "tsc --noEmit" },
devDependencies: {
"@getpaseo/plugin": "0.7.0",
"@tanstack/react-query": "^5.90.11",
"@types/react": "~19.2.0",
react: "19.1.0",
"react-native": "0.81.5",
typescript: "^5.9.3",
zod: "^4.4.3",
},
});
expect(await readdir(directory)).not.toContain("paseo-plugin.d.ts");
await expect(readFile(path.join(directory, "index.ts"), "utf8")).resolves.toContain(
'from "./main.client"',
);
packages/cli/src/commands/plugin/scaffold.ts
+2 -361
View File
@@ -1,364 +1,7 @@
import { mkdir, readdir, writeFile } from "node:fs/promises";
import path from "node:path";
import { PluginIdSchema } from "@getpaseo/protocol/messages";
const SDK_DECLARATIONS = `declare module "@getpaseo/plugin/server" {
import type { PaseoApi } from "@getpaseo/client";
import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
export interface PluginRpcContract<
InputSchema extends ZodType = ZodType,
OutputSchema extends ZodType = ZodType,
> {
name: string;
input: InputSchema;
output: OutputSchema;
}
export interface PluginAttachmentItem {
id: string;
identifier: string;
title: string;
subtitle?: string;
url: string;
text: string;
resourceType: string;
}
export interface PluginAttachmentSearchPayload {
items: PluginAttachmentItem[];
}
export interface PluginAttachmentSourceContribution {
id: string;
title: string;
icon: string;
pickerTitle: string;
searchPlaceholder: string;
search: PluginRpcContract;
}
export interface PluginHandlerContext {
paseo: PaseoApi;
}
export function defineRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(definition: {
name: string;
input: InputSchema;
output: OutputSchema;
}): PluginRpcContract<InputSchema, OutputSchema>;
export function defineAttachmentSource<Definition extends PluginAttachmentSourceContribution>(
definition: Definition,
): Definition;
export const PluginAttachmentItemSchema: import("zod").ZodType<PluginAttachmentItem>;
export const PluginAttachmentSearchPayloadSchema: import("zod").ZodType<PluginAttachmentSearchPayload>;
}
declare module "@getpaseo/plugin/react-native" {
import type { ComponentType, FunctionComponent, ReactNode } from "react";
export interface PluginIconProps {
name: string;
size?: number;
color?: string;
}
export interface ModalProps {
title: string;
icon?: ReactNode;
open: boolean;
onOpenChange(open: boolean): void;
children: ReactNode;
}
export interface ModalContentProps {
children: ReactNode;
}
export interface ModalComponent extends FunctionComponent<ModalProps> {
Content: ComponentType<ModalContentProps>;
}
export type ToastVariant = "default" | "info" | "success" | "warning" | "error";
export interface ToastOptions {
variant?: ToastVariant;
durationMs?: number;
}
export interface ToastApi {
show(message: string, options?: ToastOptions): void;
error(message: string): void;
}
export const Icon: ComponentType<PluginIconProps>;
export const Modal: ModalComponent;
export function useToast(): ToastApi;
}
declare module "@getpaseo/plugin" {
import type { ComponentType } from "react";
import type { PaseoApi } from "@getpaseo/client";
import type { AgentTimelineItem } from "@getpaseo/protocol/agent-types";
import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
import type {
PluginAttachmentSourceContribution,
PluginHandlerContext,
PluginRpcContract,
} from "@getpaseo/plugin/server";
export {
PluginAttachmentItemSchema,
PluginAttachmentSearchPayloadSchema,
defineAttachmentSource,
defineRpc,
type PluginAttachmentItem,
type PluginAttachmentSearchPayload,
type PluginAttachmentSourceContribution,
type PluginHandlerContext,
type PluginRpcContract,
} from "@getpaseo/plugin/server";
export interface PluginTheme {
readonly colors: {
readonly surface0: string;
readonly surface1: string;
readonly surface2: string;
readonly border: string;
readonly foreground: string;
readonly foregroundMuted: string;
readonly accent: string;
readonly accentForeground: string;
readonly statusSuccess: string;
readonly statusWarning: string;
readonly statusDanger: string;
};
}
export interface PluginHostProps {
theme: PluginTheme;
host: { id: string; label: string };
layout: { compact: boolean; platform: "ios" | "android" | "web" };
}
interface PluginNavigableHostProps extends PluginHostProps {
/** Client-owned navigation. Undefined on older hosts; hide dependent affordances when absent. */
readonly navigation?: {
readonly openAgent: (input: { readonly agentId: string }) => void;
readonly openWorkspace: (input: { readonly workspaceId: string }) => void;
};
}
export interface PluginSurfaceProps extends PluginNavigableHostProps {}
export interface PluginIconProps {
name: string;
size?: number;
color?: string;
}
export interface PluginWorkspaceSnapshot {
readonly id: string;
readonly projectId: string;
readonly projectDisplayName: string;
readonly projectRootPath: string;
readonly directory: string;
readonly projectKind: "git" | "non_git" | "directory";
readonly kind: "directory" | "local_checkout" | "checkout" | "worktree";
readonly name: string;
readonly title: string | null;
readonly status: "needs_input" | "failed" | "running" | "attention" | "done";
readonly statusEnteredAt: string | null;
readonly archivingAt: string | null;
readonly diffStat: { readonly additions: number; readonly deletions: number } | null;
}
export interface PluginAgentSnapshot {
readonly id: string;
readonly workspaceId: string;
readonly provider: string;
readonly status: "initializing" | "idle" | "running" | "error" | "closed";
readonly createdAt: string;
readonly updatedAt: string;
readonly lastActivityAt: string;
readonly title: string | null;
readonly cwd: string;
readonly model: string | null;
readonly currentModeId: string | null;
readonly thinkingOptionId: string | null;
readonly requiresAttention: boolean;
readonly attentionReason: "finished" | "error" | "permission" | null;
readonly parentAgentId: string | null;
readonly labels: Readonly<Record<string, string>>;
}
export interface PluginWorkspacePanelProps extends PluginNavigableHostProps {
context: "workspace";
workspaceId: string;
}
export interface PluginAgentPanelProps extends PluginNavigableHostProps {
context: "agent";
workspaceId: string;
agentId: string;
}
export interface PluginComposerPillProps extends PluginHostProps {
workspaceId: string;
agentId: string;
}
export interface PluginComposerPillContribution {
id: string;
title: string;
workspaceId: string;
agentId: string;
Component: ComponentType<PluginComposerPillProps>;
onPress(): void | Promise<void>;
}
export type PluginPanelLocation = "workspace" | "explorer";
export interface PluginOpenPanelOptions { location?: PluginPanelLocation; }
export interface PluginClientOpenPanelOptions extends PluginOpenPanelOptions {
workspaceId: string;
agentId?: string;
}
export type PluginWorkspacePanelContribution =
| { id: string; title: string; icon: string; locations?: readonly PluginPanelLocation[]; context: "workspace"; Component: ComponentType<PluginWorkspacePanelProps> }
| { id: string; title: string; icon: string; locations?: readonly PluginPanelLocation[]; context: "agent"; Component: ComponentType<PluginAgentPanelProps> };
export interface PluginSidebarContribution {
id: string;
title: string;
icon: string;
surface: string;
}
export interface PluginThemeColors {
background: string;
foreground: string;
raised: string;
control: string;
border: string;
accent?: string;
mutedForeground: string;
ring: string;
}
export interface PluginThemeContribution {
id: string;
name: string;
appearance: "light" | "dark";
colors: PluginThemeColors;
}
export interface PluginSurfaceContribution {
id: string;
Component: ComponentType<PluginSurfaceProps>;
}
export type PluginTimelineData = null | boolean | number | string | PluginTimelineData[] | { [key: string]: PluginTimelineData };
export interface PluginTimelineItem { type: "plugin"; kind: string; version: number; data: PluginTimelineData; }
export interface PluginTimelineTransformResult { items: PluginTimelineItem[]; }
export type PluginTimelineTransformerContribution<ItemType extends AgentTimelineItem["type"] = AgentTimelineItem["type"]> =
ItemType extends AgentTimelineItem["type"]
? {
id: string;
query: { itemType: ItemType };
transform(input: { item: Extract<AgentTimelineItem, { type: ItemType }> }): PluginTimelineTransformResult | undefined;
}
: never;
export interface PluginTimelineItemProps<Data = unknown> extends PluginHostProps {
agentId: string;
item: { type: "plugin"; kind: string; version: number; data: Data };
timestamp: Date;
}
export interface PluginTimelineRendererContribution<Schema extends ZodType = ZodType> {
kind: string;
version: number;
schema: Schema;
Component: ComponentType<PluginTimelineItemProps<ZodOutput<Schema>>>;
}
export interface PluginCommandCapabilities {
paseo: PaseoApi;
rpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
contract: PluginRpcContract<InputSchema, OutputSchema>,
input: ZodInput<InputSchema>,
): Promise<ZodOutput<OutputSchema>>;
openSurface(id: string): void;
}
export interface PluginGlobalCommandContext extends PluginCommandCapabilities {
context: "global";
}
export interface PluginWorkspaceCommandContext extends PluginCommandCapabilities {
context: "workspace";
workspace: PluginWorkspaceSnapshot;
openPanel(id: string, options?: PluginOpenPanelOptions): void;
}
export interface PluginAgentCommandContext extends PluginCommandCapabilities {
context: "agent";
workspace: PluginWorkspaceSnapshot;
agent: PluginAgentSnapshot;
openPanel(id: string, options?: PluginOpenPanelOptions): void;
}
export interface PluginClientContext extends PluginCommandCapabilities {
addComposerPill(contribution: PluginComposerPillContribution): PluginCleanup;
openPanel(id: string, options: PluginClientOpenPanelOptions): void;
}
export type PluginClientContribution = (client: PluginClientContext) => PluginCleanup;
export type PluginCommandCenterItemContribution =
| { id: string; title: string; icon: string; keywords?: readonly string[]; context: "global"; onSelect(context: PluginGlobalCommandContext): void | Promise<void> }
| { id: string; title: string; icon: string; keywords?: readonly string[]; context: "workspace"; onSelect(context: PluginWorkspaceCommandContext): void | Promise<void> }
| { id: string; title: string; icon: string; keywords?: readonly string[]; context: "agent"; onSelect(context: PluginAgentCommandContext): void | Promise<void> };
export interface PluginContext {
handle<InputSchema extends ZodType, OutputSchema extends ZodType>(
contract: PluginRpcContract<InputSchema, OutputSchema>,
handler: (
input: ZodOutput<InputSchema>,
context: PluginHandlerContext,
) => ZodInput<OutputSchema> | Promise<ZodInput<OutputSchema>>,
): void;
addSurface(id: string, Component: ComponentType<PluginSurfaceProps>): void;
addSidebarItem(contribution: PluginSidebarContribution): void;
addWorkspacePanel(contribution: PluginWorkspacePanelContribution): void;
addCommandCenterItem(contribution: PluginCommandCenterItemContribution): void;
addClientSide(contribution: PluginClientContribution): void;
addAttachmentSource(contribution: PluginAttachmentSourceContribution): void;
addTheme(contribution: PluginThemeContribution): void;
addTimelineTransformer<ItemType extends AgentTimelineItem["type"]>(contribution: PluginTimelineTransformerContribution<ItemType>): void;
addTimelineRenderer<Schema extends ZodType>(contribution: PluginTimelineRendererContribution<Schema>): void;
}
export type PluginCleanup = () => void | Promise<void>;
export type PluginContribution = (plugin: PluginContext) => PluginCleanup;
export const Icon: ComponentType<PluginIconProps>;
export function useRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
contract: PluginRpcContract<InputSchema, OutputSchema>,
): (input: ZodInput<InputSchema>) => Promise<ZodOutput<OutputSchema>>;
export function usePaseo(): PaseoApi;
export function useWorkspace<Selection>(
workspaceId: string,
selector: (workspace: PluginWorkspaceSnapshot) => Selection,
): Selection | null;
export function useAgent<Selection>(
agentId: string,
selector: (agent: PluginAgentSnapshot) => Selection,
): Selection | null;
}
`;
import { resolveCliVersion } from "../../version.js";
const TSCONFIG = {
compilerOptions: {
@@ -432,8 +75,7 @@ export async function scaffoldPluginDirectory(
version: "0.0.0",
scripts: { typecheck: "tsc --noEmit" },
devDependencies: {
"@getpaseo/client": "^0.4.0",
"@getpaseo/protocol": "^0.6.1",
"@getpaseo/plugin": resolveCliVersion(),
"@tanstack/react-query": "^5.90.11",
"@types/react": "~19.2.0",
react: "19.1.0",
@@ -446,7 +88,6 @@ export async function scaffoldPluginDirectory(
["paseo-plugin.json", `${JSON.stringify({ id }, null, 2)}\n`],
["package.json", `${JSON.stringify(packageJson, null, 2)}\n`],
["tsconfig.json", `${JSON.stringify(TSCONFIG, null, 2)}\n`],
["paseo-plugin.d.ts", SDK_DECLARATIONS],
["index.ts", ENTRY],
["main.client.tsx", CLIENT_SURFACE],
]);
packages/client/src/daemon-client.test.ts
+43
View File
@@ -1988,6 +1988,49 @@ test("file context action RPCs correlate success and error responses", async ()
});
});
test("serializes plugin source suffixes through the legacy path field", async () => {
const mock = createMockTransport();
const client = new DaemonClient({
url: "ws://test",
clientId: "clsk_plugin_source",
logger: createMockLogger(),
reconnect: { enabled: false },
transportFactory: () => mock.transport,
});
clients.push(client);
const connectPromise = client.connect();
mock.triggerOpen();
await connectPromise;
const installPromise = client.installPluginSource({
source: "owner/repository:plugins/review",
});
const request = parseSentFrame(mock.sent.at(-1));
expect(request).toEqual({
type: "plugin.source.install.request",
requestId: expect.any(String),
source: "owner/repository",
pluginPath: "plugins/review",
});
mock.triggerMessage(
wrapSessionMessage({
type: "plugin.source.install.response",
payload: {
requestId: request.requestId,
plugin: {
id: "review",
path: "/plugins/review",
enabled: true,
status: "running",
},
},
}),
);
await expect(installPromise).resolves.toMatchObject({ id: "review", status: "running" });
});
test("a connection loss rejects an in-flight file context action", async () => {
const mock = createMockTransport();
const client = new DaemonClient({
packages/client/src/daemon-client.ts
+10 -2
View File
@@ -1,6 +1,7 @@
import type { z } from "zod";
import { CLIENT_CAPS, type ClientCapability } from "@getpaseo/protocol/client-capabilities";
import type { AgentAttentionNotificationPayload } from "@getpaseo/protocol/agent-attention-notification";
import { parsePluginSourceReference } from "@getpaseo/protocol/plugin-source-reference";
import {
AgentCreateFailedStatusPayloadSchema,
AgentCreatedStatusPayloadSchema,
@@ -4971,12 +4972,19 @@ export class DaemonClient {
source: string;
id?: string;
ref?: string;
pluginPath?: string;
}): Promise<PluginListItem> {
const requestId = this.createRequestId();
const reference = parsePluginSourceReference(input.source);
const payload = await this.sendCorrelatedSessionRequest({
requestId,
message: { type: "plugin.source.install.request", requestId, ...input },
message: {
type: "plugin.source.install.request",
requestId,
source: reference.source,
...(reference.pluginPath ? { pluginPath: reference.pluginPath } : {}),
...(input.id ? { id: input.id } : {}),
...(input.ref ? { ref: input.ref } : {}),
},
responseType: "plugin.source.install.response",
});
return payload.plugin;
packages/protocol/src/messages.plugins.test.ts
+8 -1
View File
@@ -53,8 +53,15 @@ describe("plugin protocol compatibility", () => {
SessionInboundMessageSchema.parse({
type: "plugin.source.install.request",
requestId: "request-install",
source: "owner/repository",
source: "owner/repository:plugins/review",
ref: "main",
}).type,
).toBe("plugin.source.install.request");
expect(
SessionInboundMessageSchema.parse({
type: "plugin.source.install.request",
requestId: "request-install-old-client",
source: "owner/repository",
pluginPath: "plugins/review",
}).type,
).toBe("plugin.source.install.request");
packages/protocol/src/messages.ts
+1
View File
@@ -1465,6 +1465,7 @@ export const PluginSourceInstallRequestSchema = z.object({
source: z.string().min(1),
id: PluginIdSchema.optional(),
ref: z.string().min(1).optional(),
// COMPAT(plugin-source-path): accepted for v0.7 clients; remove after 2027-09-01.
pluginPath: z.string().min(1).optional(),
});
packages/protocol/src/plugin-source-reference.test.ts
+35
View File
@@ -0,0 +1,35 @@
import { describe, expect, it } from "vitest";
import { parsePluginSourceReference } from "./plugin-source-reference.js";
describe("plugin source references", () => {
it.each([
["owner/repository", "owner/repository", undefined],
["owner/repository:plugins/review", "owner/repository", "plugins/review"],
[
"https://example.test:8443/owner/repository.git",
"https://example.test:8443/owner/repository.git",
undefined,
],
[
"https://example.test:8443/owner/repository.git:plugins/review",
"https://example.test:8443/owner/repository.git",
"plugins/review",
],
["git@example.test:owner/repository.git", "git@example.test:owner/repository.git", undefined],
[
"git@example.test:owner/repository.git:plugins/review",
"git@example.test:owner/repository.git",
"plugins/review",
],
["file:///D:/plugins/repository", "file:///D:/plugins/repository", undefined],
[
"file:///D:/plugins/repository:plugins/review",
"file:///D:/plugins/repository",
"plugins/review",
],
["D:\\plugins\\repository", "D:\\plugins\\repository", undefined],
["D:\\plugins\\repository:plugins/review", "D:\\plugins\\repository", "plugins/review"],
])("parses %s", (reference, source, pluginPath) => {
expect(parsePluginSourceReference(reference)).toEqual({ source, pluginPath });
});
});
packages/protocol/src/plugin-source-reference.ts
+47
View File
@@ -0,0 +1,47 @@
export interface PluginSourceReference {
source: string;
pluginPath: string | undefined;
}
export function parsePluginSourceReference(reference: string): PluginSourceReference {
const separator = reference.lastIndexOf(":");
if (separator === -1) return { source: reference, pluginPath: undefined };
const pluginPath = reference.slice(separator + 1);
if (!isPortableRelativePluginPath(pluginPath)) {
return { source: reference, pluginPath: undefined };
}
const scheme = reference.indexOf("://");
if (scheme !== -1) {
const pathStart = reference.indexOf("/", scheme + 3);
if (pathStart === -1 || separator < pathStart) {
return { source: reference, pluginPath: undefined };
}
} else {
const scpSeparator = reference.match(/^[^/@\s]+@[^:\s]+:/)?.[0].length;
if (scpSeparator !== undefined && separator === scpSeparator - 1) {
return { source: reference, pluginPath: undefined };
}
}
return { source: reference.slice(0, separator), pluginPath };
}
export function formatPluginSourceReference(
source: string,
pluginPath: string | undefined,
): string {
if (pluginPath === undefined) return source;
if (!isPortableRelativePluginPath(pluginPath)) {
throw new Error("Plugin path must be a portable path relative to the repository");
}
return `${source}:${pluginPath}`;
}
function isPortableRelativePluginPath(pluginPath: string): boolean {
if (pluginPath === ".") return true;
if (!pluginPath || pluginPath.startsWith("/") || pluginPath.startsWith("\\")) return false;
if (/^[A-Za-z]:/.test(pluginPath) || pluginPath.includes(":")) return false;
return pluginPath.split(/[\\/]/).every((part) => part !== "" && part !== "." && part !== "..");
}
packages/server/src/server/plugins/index.posix.test.ts
+98 -3
View File
@@ -1,4 +1,4 @@
import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { pathToFileURL } from "node:url";
@@ -278,12 +278,12 @@ describe("PluginService", () => {
await service.start();
await expect(
service.installSource({ source: repository, pluginPath: "plugins/review" }),
service.installSource({ source: `${repository}:plugins/review` }),
).resolves.toMatchObject({ id: "local-monorepo", path: pluginDirectory, status: "running" });
await service.stopAllPlugins();
}, 20_000);
it("keeps the running commit when a Git update fails validation", async () => {
it("keeps the running commit when a Git update build command fails", async () => {
const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
roots.push(home);
const repository = await mkdtemp(path.join(tmpdir(), "paseo-plugin-repository-"));
@@ -313,6 +313,15 @@ describe("PluginService", () => {
const installedPath = installed.path;
const installedCommit = installed.commit;
await writeFile(
path.join(repository, "paseo-plugin.json"),
JSON.stringify({
id: "git-update",
build: [
[process.execPath, "-e", 'process.stderr.write("build exploded") ; process.exit(1)'],
],
}),
);
await writeFile(
path.join(repository, "index.ts"),
'export default function contribute(plugin: unknown) { void plugin; throw new Error("broken update"); }',
@@ -321,6 +330,7 @@ describe("PluginService", () => {
await runGitCommand(["commit", "-m", "broken update"], { cwd: repository });
await expect(service.updateSources("git-update")).rejects.toThrow();
expect(await readdir(path.join(home, "plugins", ".staging"))).toEqual([]);
expect(service.catalog()).toEqual([
expect.objectContaining({ id: "git-update", clientBundle: expect.any(String) }),
]);
@@ -335,6 +345,91 @@ describe("PluginService", () => {
await service.stopAllPlugins();
}, 30_000);
it("runs Git build commands in staging before validation and activation on install and update", async () => {
const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
roots.push(home);
const repository = await mkdtemp(path.join(tmpdir(), "paseo-plugin-repository-"));
roots.push(repository);
await runGitCommand(["init", "-b", "main"], { cwd: repository });
await runGitCommand(["config", "user.name", "Paseo Tests"], { cwd: repository });
await runGitCommand(["config", "user.email", "paseo@example.test"], { cwd: repository });
await writeFile(
path.join(repository, "paseo-plugin.json"),
JSON.stringify({
id: "prepared-git-plugin",
build: [
[
process.execPath,
"-e",
'require("node:fs").writeFileSync(process.argv[1], "prepared")',
"build-marker;touch shell-injection",
],
],
}),
);
await writeFile(path.join(repository, "index.ts"), "export default () => () => {};\n");
await runGitCommand(["add", "-A"], { cwd: repository });
await runGitCommand(["commit", "-m", "initial"], { cwd: repository });
const events: string[] = [];
const running = new Set<string>();
const runtime: TestPluginRuntime = {
catalog: () => [...running].map((id) => ({ id, clientBundle: "bundle" })),
invoke: async () => undefined,
getLogs: () => [],
clearLogs: () => undefined,
validatePlugin: async (directory) => {
events.push(
`validate:${await readFile(path.join(directory, "build-marker;touch shell-injection"), "utf8")}`,
);
},
startPlugin: async (pluginId) => {
events.push("start");
running.add(pluginId);
},
stopPluginById: async (pluginId) => running.delete(pluginId),
stopAll: async () => running.clear(),
subscribe: () => () => undefined,
bindPaseoSessionHost: () => undefined,
};
const service = createService(
home,
{},
{
runtime,
managedSources: new ManagedPluginSources(home),
},
);
await service.start();
const installed = await service.installSource({ source: pathToFileURL(repository).href });
expect(events).toEqual(["validate:prepared", "start"]);
await expect(stat(path.join(installed.path, "shell-injection"))).rejects.toThrow();
await writeFile(
path.join(repository, "paseo-plugin.json"),
JSON.stringify({
id: "prepared-git-plugin",
build: [
[
process.execPath,
"-e",
'require("node:fs").writeFileSync("build-marker;touch shell-injection", "updated")',
],
],
}),
);
await runGitCommand(["add", "-A"], { cwd: repository });
await runGitCommand(["commit", "-m", "prepared update"], { cwd: repository });
await expect(service.updateSources("prepared-git-plugin")).resolves.toEqual([
expect.objectContaining({ id: "prepared-git-plugin", updated: true }),
]);
expect(events).toEqual(["validate:prepared", "start", "validate:updated", "start"]);
await service.stopAllPlugins();
}, 30_000);
it("activates an update when the enabled plugin previously failed to start", async () => {
const home = await mkdtemp(path.join(tmpdir(), "paseo-plugin-home-"));
roots.push(home);
packages/server/src/server/plugins/index.ts
+29 -16
View File
@@ -9,9 +9,11 @@ import {
type PluginSourceStatusItem,
type PluginSourceUpdateItem,
} from "@getpaseo/protocol/messages";
import { parsePluginSourceReference } from "@getpaseo/protocol/plugin-source-reference";
import type { DaemonConfigStore } from "../daemon-config-store.js";
import { type ManagedPluginCandidate, ManagedPluginSources } from "./managed-source.js";
import { readPluginManifest } from "./manifest.js";
import { runPluginBuild } from "./preparation.js";
import { PluginRuntime } from "./runtime.js";
interface PluginRuntimePort {
@@ -165,27 +167,36 @@ export class PluginService {
source: string;
id?: string;
ref?: string;
pluginPath?: string;
}): Promise<PluginListItem> {
const directory = path.resolve(input.source);
const info = await stat(directory).catch(() => null);
const directDirectory = path.resolve(input.source);
const directInfo = await stat(directDirectory).catch(() => null);
const reference = directInfo?.isDirectory()
? { source: input.source, pluginPath: undefined }
: parsePluginSourceReference(input.source);
const directory = path.resolve(reference.source);
const info = directInfo?.isDirectory() ? directInfo : await stat(directory).catch(() => null);
if (info?.isDirectory()) {
if (input.ref) throw new Error("Plugin --ref is only valid for Git sources");
const pluginDirectory = resolveLocalPluginPath(directory, input.pluginPath);
const pluginDirectory = resolveLocalPluginPath(directory, reference.pluginPath);
return this.installDirectory({ path: pluginDirectory, id: input.id });
}
const managedSources = this.requireManagedSources();
return this.enqueue(async () => {
let candidate = await managedSources.prepareInstall(input);
const pluginId = PluginIdSchema.parse(input.id ?? candidate.defaultId);
if (this.configStore.get().plugins?.[pluginId]) {
await managedSources.discard(candidate);
throw new Error(
`Plugin ID "${pluginId}" is already configured; choose another ID with --id`,
);
}
candidate = await managedSources.place(pluginId, candidate);
let candidate = await managedSources.prepareInstall({
...input,
source: reference.source,
pluginPath: reference.pluginPath,
});
let pluginId: string;
try {
await runPluginBuild(candidate.directory, candidate.build, this.logger);
pluginId = PluginIdSchema.parse(input.id ?? candidate.defaultId);
if (this.configStore.get().plugins?.[pluginId]) {
throw new Error(
`Plugin ID "${pluginId}" is already configured; choose another ID with --id`,
);
}
candidate = await managedSources.place(pluginId, candidate);
await this.validateCandidate(candidate);
} catch (error) {
await managedSources.discard(candidate);
@@ -382,8 +393,10 @@ export class PluginService {
updated: false,
};
}
const candidate = await managedSources.place(pluginId, prepared.candidate);
let candidate = prepared.candidate;
try {
await runPluginBuild(candidate.directory, candidate.build, this.logger);
candidate = await managedSources.place(pluginId, candidate);
await this.validateCandidate(candidate);
} catch (error) {
await managedSources.discard(candidate);
@@ -481,11 +494,11 @@ export class PluginService {
function resolveLocalPluginPath(directory: string, pluginPath: string | undefined): string {
if (!pluginPath) return directory;
if (path.isAbsolute(pluginPath)) throw new Error("Plugin --path must be relative to the source");
if (path.isAbsolute(pluginPath)) throw new Error("Plugin path must be relative to the source");
const pluginDirectory = path.resolve(directory, pluginPath);
const relative = path.relative(directory, pluginDirectory);
const escapesSource =
relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
if (escapesSource) throw new Error("Plugin --path must stay inside the source directory");
if (escapesSource) throw new Error("Plugin path must stay inside the source directory");
return pluginDirectory;
}
packages/server/src/server/plugins/managed-source.ts
+8 -4
View File
@@ -7,6 +7,7 @@ import { PluginIdSchema, type PluginSourceStatusItem } from "@getpaseo/protocol/
import { runGitCommand } from "../../utils/run-git-command.js";
import { ensurePrivateDirectory, writePrivateFileAtomicSync } from "../private-files.js";
import { readPluginManifest } from "./manifest.js";
import type { PluginManifest } from "./manifest.js";
const GIT_TIMEOUT_MS = 120_000;
const GIT_ENV = { GIT_TERMINAL_PROMPT: "0" } as const;
@@ -27,6 +28,7 @@ const ManagedPluginRecordsSchema = z.record(PluginIdSchema, ManagedPluginRecordS
export interface ManagedPluginRecord extends z.infer<typeof ManagedPluginRecordSchema> {}
export interface ManagedPluginCandidate {
build: PluginManifest["build"];
defaultId: string;
directory: string;
record: ManagedPluginRecord;
@@ -76,8 +78,9 @@ export class ManagedPluginSources {
await checkout(checkoutRoot, resolution.commit);
const directory = path.resolve(checkoutRoot, pluginPath);
assertPluginPath(checkoutRoot, directory);
const { id: defaultId } = await readPluginManifest(directory);
const { id: defaultId, build } = await readPluginManifest(directory);
return {
build,
defaultId,
directory,
record: {
@@ -207,8 +210,9 @@ export class ManagedPluginSources {
await checkout(checkoutRoot, commit);
const directory = path.resolve(checkoutRoot, record.pluginPath);
assertPluginPath(checkoutRoot, directory);
const { id: defaultId } = await readPluginManifest(directory);
const { id: defaultId, build } = await readPluginManifest(directory);
return {
build,
defaultId,
directory,
versionRoot: stagingRoot,
@@ -259,10 +263,10 @@ function redactRemoteCredentials(remote: string): string {
function normalizePluginPath(pluginPath: string | undefined): string {
if (!pluginPath || pluginPath === ".") return ".";
if (path.isAbsolute(pluginPath))
throw new Error("Plugin --path must be relative to the repository");
throw new Error("Plugin path must be relative to the repository");
const normalized = path.normalize(pluginPath);
if (normalized === ".." || normalized.startsWith(`..${path.sep}`)) {
throw new Error("Plugin --path must stay inside the repository");
throw new Error("Plugin path must stay inside the repository");
}
return normalized;
}
packages/server/src/server/plugins/manifest.test.ts
+32
View File
@@ -0,0 +1,32 @@
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { readPluginManifest } from "./manifest.js";
const directories: string[] = [];
afterEach(async () => {
await Promise.all(directories.splice(0).map((directory) => rm(directory, { recursive: true })));
});
describe("plugin manifest", () => {
it("accepts only non-empty argv arrays for build commands", async () => {
const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-manifest-"));
directories.push(directory);
const manifest = path.join(directory, "paseo-plugin.json");
await writeFile(
manifest,
JSON.stringify({ id: "prepared", build: [["pnpm", "install", "--frozen-lockfile"]] }),
);
await expect(readPluginManifest(directory)).resolves.toMatchObject({
build: [["pnpm", "install", "--frozen-lockfile"]],
});
for (const build of [[], [[]], [["pnpm", ""]], [["pnpm", 1]], "pnpm install"]) {
await writeFile(manifest, JSON.stringify({ id: "prepared", build }));
await expect(readPluginManifest(directory)).rejects.toThrow();
}
});
});
packages/server/src/server/plugins/manifest.ts
+9 -1
View File
@@ -4,7 +4,15 @@ import { z } from "zod";
import { PluginIdSchema } from "@getpaseo/protocol/messages";
const MANIFEST_FILENAME = "paseo-plugin.json";
const PluginManifestSchema = z.object({ id: PluginIdSchema }).strict();
const PluginBuildCommandSchema = z
.array(z.string().refine((argument) => argument.trim().length > 0))
.min(1);
const PluginManifestSchema = z
.object({
id: PluginIdSchema,
build: z.array(PluginBuildCommandSchema).min(1).optional(),
})
.strict();
export type PluginManifest = z.infer<typeof PluginManifestSchema>;
packages/server/src/server/plugins/preparation.ts
+71
View File
@@ -0,0 +1,71 @@
import { spawn } from "node:child_process";
import type pino from "pino";
import type { PluginManifest } from "./manifest.js";
const OUTPUT_LIMIT = 64 * 1024;
export async function runPluginBuild(
directory: string,
commands: PluginManifest["build"],
logger: pino.Logger,
): Promise<void> {
for (const command of commands ?? []) {
logger.info({ directory, command }, "Running plugin build command");
const result = await run(command, directory);
if (result.stdout)
logger.info({ directory, command, output: result.stdout }, "Plugin build stdout");
if (result.stderr)
logger.info({ directory, command, output: result.stderr }, "Plugin build stderr");
if (result.error) {
throw new Error(
`Plugin build command failed to start: ${formatCommand(command)}\n${result.error.message}`,
);
}
if (result.exitCode !== 0) {
throw new Error(
`Plugin build command failed (exit ${result.exitCode}): ${formatCommand(command)}${formatOutput(result)}`,
);
}
}
}
function run(command: string[], directory: string): Promise<CommandResult> {
return new Promise((resolve) => {
const executable = command[0]!;
const arguments_ = command.slice(1);
const child = spawn(executable, arguments_, { cwd: directory, shell: false });
let stdout = "";
let stderr = "";
let error: Error | undefined;
child.stdout.on("data", (chunk: Buffer | string) => {
stdout = appendOutput(stdout, chunk.toString());
});
child.stderr.on("data", (chunk: Buffer | string) => {
stderr = appendOutput(stderr, chunk.toString());
});
child.once("error", (spawnError) => {
error = spawnError;
});
child.once("close", (exitCode) => resolve({ exitCode, stdout, stderr, error }));
});
}
function appendOutput(current: string, next: string): string {
return `${current}${next}`.slice(-OUTPUT_LIMIT);
}
function formatCommand(command: string[]): string {
return command.map((argument) => JSON.stringify(argument)).join(" ");
}
function formatOutput(result: CommandResult): string {
const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
return output ? `\n${output}` : "";
}
interface CommandResult {
exitCode: number | null;
stdout: string;
stderr: string;
error?: Error;
}
packages/server/src/server/session.ts
+3 -3
View File
@@ -4,6 +4,7 @@ import { lstat, mkdir, mkdtemp, rename, rm, stat } from "node:fs/promises";
import { basename, resolve, sep } from "path";
import { homedir } from "node:os";
import { CLIENT_CAPS, type ClientCapability } from "@getpaseo/protocol/client-capabilities";
import { formatPluginSourceReference } from "@getpaseo/protocol/plugin-source-reference";
import {
serializeAgentStreamEvent,
type AgentSnapshotPayload,
@@ -479,7 +480,6 @@ export interface SessionOptions {
source: string;
id?: string;
ref?: string;
pluginPath?: string;
}): Promise<import("@getpaseo/protocol/messages").PluginListItem>;
statusSources(
pluginId?: string,
@@ -2109,10 +2109,10 @@ export class Session {
if (!this.pluginRuntime) throw new Error("Plugin service is unavailable");
return this.pluginRuntime
.installSource({
source: msg.source,
// COMPAT(plugin-source-path): accepted for v0.7 clients; remove after 2027-09-01.
source: formatPluginSourceReference(msg.source, msg.pluginPath),
...(msg.id ? { id: msg.id } : {}),
...(msg.ref ? { ref: msg.ref } : {}),
...(msg.pluginPath ? { pluginPath: msg.pluginPath } : {}),
})
.then((plugin) => {
this.emit({
public-docs/cli.md
+6 -3
View File
@@ -144,13 +144,16 @@ The output includes each script's lifecycle and supervised terminal ID. Services
## Plugins
> **Trust every plugin you add.** `paseo plugin add` and `paseo plugin install` mean “I trust this codebase.” Plugin 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.
Create and manage trusted plugins on a daemon:
```bash
paseo plugin init /absolute/path/to/plugin
paseo plugin install /absolute/path/to/plugin
paseo plugin add owner/repository
paseo plugin add https://git.example.com/owner/repository.git --ref main
paseo plugin add https://gitlab.com/group/repository.git --ref main
paseo plugin add owner/monorepo:plugins/review
paseo plugin status
paseo plugin update my-plugin
paseo plugin update --all
@@ -162,8 +165,8 @@ paseo plugin enable my-plugin
paseo plugin remove my-plugin
```
GitHub shorthand checks an existing host directory first. Use `--path <directory>` for a plugin in
a monorepo. `paseo plugin logs <id>` returns the plugin's recent daemon-side stdout and stderr. Add `--json` for
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 `--host <target>` for another daemon. See the
[Plugin reference](/docs/plugins/reference) for installation, trust, lifecycle, and log-retention
behavior.
public-docs/plugins/index.md
+29 -6
View File
@@ -16,7 +16,7 @@ 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.
Plugins are trusted local code. Install only code you trust: backend code runs unsandboxed with access to the daemon machine, and client contributions run inside the Paseo app.
> **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.
@@ -38,7 +38,10 @@ cd /absolute/path/to/workspace-plugin
npm install
```
`init` creates a strict TypeScript project. It does not run the package manager. `index.ts` registers contributions; client UI lives in `*.client.tsx` files.
`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.
@@ -123,11 +126,14 @@ 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 --path plugins/workspace
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:
@@ -137,9 +143,26 @@ paseo plugin update workspace-plugin
paseo plugin update --all
```
Paseo validates and compiles the new commit before replacing a running version. If startup fails,
the previous version is restored. Git installation runs no package manager or install scripts, so
published plugins must use Paseo's host-provided modules or include the source they bundle.
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
public-docs/plugins/reference.md
+30 -9
View File
@@ -29,7 +29,6 @@ my-plugin/
paseo-plugin.json
index.ts
main.client.tsx
paseo-plugin.d.ts
package.json
tsconfig.json
```
@@ -42,9 +41,9 @@ The required root manifest is `paseo-plugin.json`. It contains the default plugi
The entry point is `index.ts` at the plugin root. Plugin, surface, sidebar-item, workspace-panel, Command Center item, and attachment-source IDs start with a lowercase letter and contain lowercase letters, numbers, or hyphens.
The generated declaration file supplies `@getpaseo/plugin`, `@getpaseo/plugin/react-native`, and
`@getpaseo/plugin/server` types for local typechecking. Paseo supplies the runtime modules.
Regenerate a fresh project with the matching CLI when the plugin contract changes.
The generated `package.json` installs `@getpaseo/plugin` and the other host modules as development
dependencies for local typechecking and tests. Paseo supplies their runtime instances. Consumers do
not install them when adding the plugin.
Add runtime-specific files as the plugin grows:
@@ -883,7 +882,7 @@ paseo plugin install /absolute/path/to/plugin
paseo plugin install /absolute/path/to/plugin --id another-runtime-id
paseo plugin add owner/repository
paseo plugin add https://git.example.com/owner/repository.git --ref main
paseo plugin add owner/monorepo --path plugins/review
paseo plugin add owner/monorepo:plugins/review
paseo plugin status [id]
paseo plugin update <id>
paseo plugin update --all
@@ -899,10 +898,32 @@ Pass `--host <url>` to management commands when the target is not the CLI's defa
never deletes a directory source; it deletes the managed checkout for a Git source. The install-time
`--id` is the runtime ID and allows the same directory or repository to be installed more than once.
An existing directory wins over `owner/repository` GitHub shorthand. Omit `--ref` to track the
default branch. Explicit branches track updates; tags and commits stay pinned. Git installation
runs no package manager and no install scripts. `update` validates and compiles the candidate before
activation, then restores the installed commit if startup fails.
> **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.
An existing directory wins over `owner/repository` GitHub shorthand. Append `:relative/path` when
the plugin lives below the repository root. Omit `--ref` to track the default branch. Explicit
branches track updates; tags and commits stay pinned.
Most plugins should omit `build`. Use it only when the staged checkout must install a dependency
that Paseo does not provide, generate source or assets, or perform another required preparation
step:
```json
{
"id": "review",
"build": [
["npm", "ci"],
["npm", "run", "build"]
]
}
```
`build` is a list of non-empty argv arrays. Paseo runs each executable directly, without a shell,
from the staged plugin directory after resolving the exact commit and manifest. It never infers a
package manager or commands from lockfiles. Install and update both run `build` before validation,
compilation, activation, or replacement. A failing command reports its output, discards the
candidate, and leaves the installed/running version intact. The daemon log records each command and
output; with `--host`, execution is on that daemon host.
Run `npm run typecheck` before install or reload. Never edit the daemon config directly.