@getpaseo/cli 0.4.0-beta.2 → 0.5.0-beta.1

package/dist/commands/plugin/scaffold.js

@@ -0,0 +1,307 @@
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { PluginIdSchema } from "@getpaseo/protocol/messages";
+const SDK_DECLARATIONS = `declare module "@paseo/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 "@paseo/plugin" {
+  import type { ComponentType } from "react";
+  import type { PaseoApi } from "@getpaseo/client";
+  import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
+  import type {
+    PluginAttachmentSourceContribution,
+    PluginHandlerContext,
+    PluginRpcContract,
+  } from "@paseo/plugin/server";
+
+  export {
+    PluginAttachmentItemSchema,
+    PluginAttachmentSearchPayloadSchema,
+    defineAttachmentSource,
+    defineRpc,
+    type PluginAttachmentItem,
+    type PluginAttachmentSearchPayload,
+    type PluginAttachmentSourceContribution,
+    type PluginHandlerContext,
+    type PluginRpcContract,
+  } from "@paseo/plugin/server";
+
+  export interface PluginTheme {
+    readonly colors: {
+      readonly surface0: string;
+      readonly foreground: string;
+      readonly foregroundMuted: string;
+      readonly accent: string;
+      readonly accentForeground: string;
+      readonly statusDanger: string;
+    };
+  }
+
+  export interface PluginHostProps {
+    theme: PluginTheme;
+    host: { id: string; label: string };
+    layout: { compact: boolean; platform: "ios" | "android" | "web" };
+  }
+
+  export interface PluginSurfaceProps extends PluginHostProps {}
+
+  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 PluginHostProps {
+    context: "workspace";
+    workspaceId: string;
+  }
+
+  export interface PluginAgentPanelProps extends PluginHostProps {
+    context: "agent";
+    workspaceId: string;
+    agentId: string;
+  }
+
+  export type PluginWorkspacePanelContribution =
+    | { id: string; title: string; icon: string; context: "workspace"; Component: ComponentType<PluginWorkspacePanelProps> }
+    | { id: string; title: string; icon: string; context: "agent"; Component: ComponentType<PluginAgentPanelProps> };
+
+  export interface PluginSidebarContribution {
+    id: string;
+    title: string;
+    icon: string;
+    surface: string;
+  }
+
+  export interface PluginSurfaceContribution {
+    id: string;
+    Component: ComponentType<PluginSurfaceProps>;
+  }
+
+  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): void;
+  }
+
+  export interface PluginAgentCommandContext extends PluginCommandCapabilities {
+    context: "agent";
+    workspace: PluginWorkspaceSnapshot;
+    agent: PluginAgentSnapshot;
+    openPanel(id: string): void;
+  }
+
+  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;
+    addAttachmentSource(contribution: PluginAttachmentSourceContribution): void;
+  }
+
+  export type PluginCleanup = () => void | Promise<void>;
+  export type PluginContribution = (plugin: PluginContext) => PluginCleanup;
+
+  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;
+}
+`;
+const TSCONFIG = {
+    compilerOptions: {
+        target: "ES2020",
+        module: "ESNext",
+        moduleResolution: "Bundler",
+        lib: ["ES2023", "DOM"],
+        jsx: "react-jsx",
+        strict: true,
+        skipLibCheck: true,
+        noEmit: true,
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+    },
+    include: ["**/*.ts", "**/*.tsx"],
+};
+const ENTRY = `import type { PluginContext } from "@paseo/plugin";
+import { MainSurface } from "./main.client";
+
+export default function contribute(plugin: PluginContext) {
+  plugin.addSurface("main", MainSurface);
+  return () => {};
+}
+`;
+const CLIENT_SURFACE = `import type { PluginSurfaceProps } from "@paseo/plugin";
+import React, { useMemo } from "react";
+import { Text, View } from "react-native";
+
+export function MainSurface({ theme, layout }: PluginSurfaceProps) {
+  const styles = useMemo(
+    () => ({
+      screen: {
+        flex: 1,
+        padding: layout.compact ? 16 : 24,
+        backgroundColor: theme.colors.surface0,
+      },
+      text: { color: theme.colors.foreground },
+    }),
+    [theme, layout.compact],
+  );
+  return (
+    <View style={styles.screen}>
+      <Text style={styles.text}>Hello from my plugin</Text>
+    </View>
+  );
+}
+`;
+export async function scaffoldPluginDirectory(targetDirectory, requestedId) {
+    const directory = path.resolve(targetDirectory);
+    const id = PluginIdSchema.parse(requestedId ?? path.basename(directory));
+    await mkdir(directory, { recursive: true });
+    const existing = await readdir(directory);
+    if (existing.length > 0) {
+        throw new Error(`Plugin directory must be empty: ${directory}`);
+    }
+    const packageJson = {
+        name: id,
+        private: true,
+        version: "0.0.0",
+        scripts: { typecheck: "tsc --noEmit" },
+        devDependencies: {
+            "@getpaseo/client": "^0.4.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",
+        },
+    };
+    const files = new Map([
+        ["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],
+    ]);
+    await Promise.all([...files].map(([filename, contents]) => writeFile(path.join(directory, filename), contents, { flag: "wx" })));
+    return { id, directory };
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/commands/plugin/shared.d.ts

@@ -0,0 +1,4 @@
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+export declare function withPluginManagementClient<T>(host: string | undefined, run: (client: DaemonClient) => Promise<T>): Promise<T>;
+export declare function withPluginLogsClient<T>(host: string | undefined, run: (client: DaemonClient) => Promise<T>): Promise<T>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/commands/plugin/shared.js

@@ -0,0 +1,26 @@
+import { connectToDaemon } from "../../utils/client.js";
+async function withPluginClient(host, feature, updateMessage, run) {
+    const client = await connectToDaemon({ host });
+    if (client.getLastServerInfoMessage()?.features?.[feature] !== true) {
+        await client.close().catch(() => undefined);
+        throw {
+            code: "DAEMON_UPDATE_REQUIRED",
+            message: updateMessage,
+        };
+    }
+    try {
+        return await run(client);
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+export async function withPluginManagementClient(host, run) {
+    // COMPAT(pluginManagement): added in v0.3.1, remove gate after 2027-08-14.
+    return withPluginClient(host, "pluginManagement", "Update the host to use plugin management.", run);
+}
+export async function withPluginLogsClient(host, run) {
+    // COMPAT(pluginLogs): added in v0.4.0, remove gate after 2027-08-16.
+    return withPluginClient(host, "pluginLogs", "Update the host to view plugin logs.", run);
+}
+//# sourceMappingURL=shared.js.map

package/dist/commands/project/create.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import type { CommandOptions, SingleResult } from "../../output/index.js";
+import { type ProjectRow } from "./shared.js";
+export declare function resolveProjectPath(input: {
+    pathArg?: string;
+    cwd: string;
+    daemonTarget?: string;
+}): string;
+export declare function runCreateCommand(pathArg: string | undefined, options: CommandOptions, _command: Command): Promise<SingleResult<ProjectRow>>;
+//# sourceMappingURL=create.d.ts.map

package/dist/commands/project/create.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+import { buildDaemonConnectionCommandError, connectToDaemon } from "../../utils/client.js";
+import { projectSchema, toProjectRow } from "./shared.js";
+export function resolveProjectPath(input) {
+    if (input.daemonTarget) {
+        if (input.pathArg === undefined) {
+            throw {
+                code: "MISSING_PATH",
+                message: "Project path is required when targeting a daemon explicitly",
+                details: "Usage: paseo project create <path> --host <host>",
+            };
+        }
+        return input.pathArg;
+    }
+    return path.resolve(input.cwd, input.pathArg ?? ".");
+}
+export async function runCreateCommand(pathArg, options, _command) {
+    const projectPath = resolveProjectPath({
+        pathArg,
+        cwd: process.cwd(),
+        daemonTarget: options.host ?? process.env.PASEO_HOST,
+    });
+    const client = await connectToDaemon({ host: options.host }).catch((error) => {
+        throw buildDaemonConnectionCommandError({ host: options.host, error });
+    });
+    try {
+        const payload = await client.addProject(projectPath);
+        if (!payload.project) {
+            throw new Error(payload.error ?? "Project creation failed");
+        }
+        return { type: "single", data: toProjectRow(payload.project), schema: projectSchema };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw { code: "PROJECT_CREATE_FAILED", message };
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=create.js.map

package/dist/commands/project/delete.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+import type { CommandOptions, SingleResult } from "../../output/index.js";
+interface ProjectDeleteResult {
+    projectId: string;
+    removedWorkspaceIds: string[];
+}
+export declare function runDeleteCommand(projectId: string, options: CommandOptions, _command: Command): Promise<SingleResult<ProjectDeleteResult>>;
+export {};
+//# sourceMappingURL=delete.d.ts.map

package/dist/commands/project/delete.js

@@ -0,0 +1,33 @@
+import { buildDaemonConnectionCommandError, connectToDaemon } from "../../utils/client.js";
+const projectDeleteSchema = {
+    idField: "projectId",
+    columns: [
+        { header: "PROJECT ID", field: "projectId", width: 20 },
+        {
+            header: "REMOVED WORKSPACES",
+            field: (result) => result.removedWorkspaceIds.length,
+            width: 18,
+        },
+    ],
+};
+export async function runDeleteCommand(projectId, options, _command) {
+    const client = await connectToDaemon({ host: options.host }).catch((error) => {
+        throw buildDaemonConnectionCommandError({ host: options.host, error });
+    });
+    try {
+        const result = await client.removeProject(projectId);
+        return {
+            type: "single",
+            data: { projectId, removedWorkspaceIds: result.removedWorkspaceIds },
+            schema: projectDeleteSchema,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw { code: "PROJECT_DELETE_FAILED", message };
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=delete.js.map

package/dist/commands/project/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createProjectCommand(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/project/index.js

@@ -0,0 +1,28 @@
+import { Command } from "commander";
+import { withOutput } from "../../output/index.js";
+import { addJsonAndDaemonHostOptions } from "../../utils/command-options.js";
+import { runCreateCommand } from "./create.js";
+import { runDeleteCommand } from "./delete.js";
+import { runLsCommand } from "./ls.js";
+import { runRenameCommand } from "./rename.js";
+export function createProjectCommand() {
+    const project = new Command("project").description("Manage projects");
+    addJsonAndDaemonHostOptions(project
+        .command("create")
+        .description("Register a project directory")
+        .argument("[path]", "Project directory (default: current directory)")).action(withOutput(runCreateCommand));
+    addJsonAndDaemonHostOptions(project.command("ls").description("List projects")).action(withOutput(runLsCommand));
+    addJsonAndDaemonHostOptions(project
+        .command("rename")
+        .description("Set a project's user-visible name")
+        .argument("<project-id>", "Project id")
+        .argument("[name]", "New project name")
+        .option("--reset", "Clear the custom name and use the directory name")
+        .allowExcessArguments(false)).action(withOutput(runRenameCommand));
+    addJsonAndDaemonHostOptions(project
+        .command("delete")
+        .description("Delete a project and its workspaces")
+        .argument("<project-id>", "Project id")).action(withOutput(runDeleteCommand));
+    return project;
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/project/ls.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { CommandOptions, ListResult } from "../../output/index.js";
+import { type ProjectRow } from "./shared.js";
+export declare function runLsCommand(options: CommandOptions, _command: Command): Promise<ListResult<ProjectRow>>;
+//# sourceMappingURL=ls.d.ts.map

package/dist/commands/project/ls.js

@@ -0,0 +1,19 @@
+import { buildDaemonConnectionCommandError, connectToDaemon } from "../../utils/client.js";
+import { projectSchema, toProjectRow } from "./shared.js";
+export async function runLsCommand(options, _command) {
+    const client = await connectToDaemon({ host: options.host }).catch((error) => {
+        throw buildDaemonConnectionCommandError({ host: options.host, error });
+    });
+    try {
+        const payload = await client.listProjects();
+        return {
+            type: "list",
+            data: payload.projects.map(toProjectRow),
+            schema: projectSchema,
+        };
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=ls.js.map

package/dist/commands/project/rename.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from "commander";
+import type { CommandOptions, SingleResult } from "../../output/index.js";
+interface ProjectRenameResult {
+    projectId: string;
+    name: string | null;
+}
+export declare function resolveProjectName(input: {
+    name?: string;
+    reset?: boolean;
+}): string | null;
+export declare function runRenameCommand(projectId: string, nameArg: string | undefined, options: CommandOptions & {
+    reset?: boolean;
+}, _command: Command): Promise<SingleResult<ProjectRenameResult>>;
+export {};
+//# sourceMappingURL=rename.d.ts.map

package/dist/commands/project/rename.js

@@ -0,0 +1,50 @@
+import { buildDaemonConnectionCommandError, connectToDaemon } from "../../utils/client.js";
+const projectRenameSchema = {
+    idField: "projectId",
+    columns: [
+        { header: "PROJECT ID", field: "projectId", width: 20 },
+        { header: "NAME", field: "name", width: 30 },
+    ],
+};
+export function resolveProjectName(input) {
+    if (input.reset) {
+        if (input.name !== undefined) {
+            throw {
+                code: "INVALID_OPTIONS",
+                message: "--reset cannot be combined with a name",
+            };
+        }
+        return null;
+    }
+    const name = input.name?.trim() ?? "";
+    if (name.length === 0) {
+        throw {
+            code: "MISSING_NAME",
+            message: "Project name cannot be empty",
+            details: "Usage: paseo project rename <project-id> <name> | --reset",
+        };
+    }
+    return name;
+}
+export async function runRenameCommand(projectId, nameArg, options, _command) {
+    const name = resolveProjectName({ name: nameArg, reset: options.reset });
+    const client = await connectToDaemon({ host: options.host }).catch((error) => {
+        throw buildDaemonConnectionCommandError({ host: options.host, error });
+    });
+    try {
+        const applied = await client.renameProject(projectId, name);
+        return {
+            type: "single",
+            data: { projectId, name: applied.customName },
+            schema: projectRenameSchema,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw { code: "PROJECT_RENAME_FAILED", message };
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=rename.js.map

package/dist/commands/project/shared.d.ts

@@ -0,0 +1,11 @@
+import type { WorkspaceProjectDescriptorPayload } from "@getpaseo/protocol/messages";
+import type { OutputSchema } from "../../output/index.js";
+export interface ProjectRow {
+    projectId: string;
+    name: string;
+    kind: "git" | "non_git" | "directory";
+    path: string;
+}
+export declare const projectSchema: OutputSchema<ProjectRow>;
+export declare function toProjectRow(project: WorkspaceProjectDescriptorPayload): ProjectRow;
+//# sourceMappingURL=shared.d.ts.map

package/dist/commands/project/shared.js

@@ -0,0 +1,18 @@
+export const projectSchema = {
+    idField: "projectId",
+    columns: [
+        { header: "PROJECT ID", field: "projectId", width: 20 },
+        { header: "NAME", field: "name", width: 24 },
+        { header: "KIND", field: "kind", width: 10 },
+        { header: "PATH", field: "path", width: 42 },
+    ],
+};
+export function toProjectRow(project) {
+    return {
+        projectId: project.projectId,
+        name: project.projectDisplayName,
+        kind: project.projectKind,
+        path: project.projectRootPath,
+    };
+}
+//# sourceMappingURL=shared.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/cli",
-  "version": "0.4.0-beta.2",
+  "version": "0.5.0-beta.1",
   "description": "Paseo CLI - control your AI coding agents from the command line",
   "bin": {
     "paseo": "bin/paseo"
@@ -28,9 +28,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@getpaseo/client": "0.4.0-beta.2",
-    "@getpaseo/protocol": "0.4.0-beta.2",
-    "@getpaseo/server": "0.4.0-beta.2",
+    "@getpaseo/client": "0.5.0-beta.1",
+    "@getpaseo/protocol": "0.5.0-beta.1",
+    "@getpaseo/server": "0.5.0-beta.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "mime-types": "^2.1.35",