@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/plugins/plugin-process-protocol.d.ts

@@ -0,0 +1,120 @@
+import type { ProviderConnectRequest, ProviderCatalogOptions, ProviderEvent, ProviderInput } from "@camerontaylor/paseo-plugin/server/provider";
+import { z } from "zod";
+export interface PluginProviderMetadata {
+    hasCatalogCacheKey?: boolean;
+    id: string;
+    label: string;
+    description?: string;
+    iconPath?: string;
+}
+export type PluginProcessRequest = {
+    type: "initialize";
+    pluginId: string;
+    bundle: string;
+    appVersion: string;
+    settingsDirectory?: string;
+} | {
+    type: "provider.catalog_key";
+    requestId: string;
+    providerId: string;
+    options: ProviderCatalogOptions;
+} | {
+    type: "hook";
+    requestId: string;
+    kind: "event" | "before";
+    name: string;
+    input: unknown;
+} | {
+    type: "hook.cancel";
+    requestId: string;
+} | {
+    type: "invoke";
+    requestId: string;
+    method: string;
+    input: unknown;
+} | {
+    type: "provider.connect";
+    providerId: string;
+    connectionId: string;
+    request: ProviderConnectRequest;
+} | {
+    type: "provider.send";
+    connectionId: string;
+    acceptanceId: string;
+    input: ProviderInput;
+} | {
+    type: "provider.close";
+    connectionId: string;
+} | {
+    type: "shutdown";
+} | {
+    type: "paseo_frame";
+    data: string | Uint8Array;
+    isBinary: boolean;
+} | {
+    type: "paseo_close";
+};
+export type PluginProcessMessage = {
+    type: "settings.changed";
+    settingsId: string;
+} | {
+    type: "hooks.changed";
+    hooks: {
+        events: string[];
+        before: string[];
+    };
+} | {
+    type: "ready";
+    methods: string[];
+    providers: PluginProviderMetadata[];
+    hooks?: {
+        events: string[];
+        before: string[];
+    };
+} | {
+    type: "result";
+    requestId: string;
+    output: unknown;
+} | {
+    type: "error";
+    requestId: string;
+    error: string;
+} | {
+    type: "fatal";
+    error: string;
+} | {
+    type: "provider.connected";
+    connectionId: string;
+    version: number;
+    capabilities: readonly string[];
+} | {
+    type: "provider.connect_failed";
+    connectionId: string;
+    error: string;
+} | {
+    type: "provider.accepted";
+    connectionId: string;
+    acceptanceId: string;
+} | {
+    type: "provider.rejected";
+    connectionId: string;
+    acceptanceId: string;
+    error: string;
+} | {
+    type: "provider.event";
+    connectionId: string;
+    event: ProviderEvent;
+} | {
+    type: "provider.closed";
+    connectionId: string;
+    error?: string;
+} | {
+    type: "paseo_frame";
+    data: string | Uint8Array;
+    isBinary: boolean;
+} | {
+    type: "paseo_close";
+};
+export declare const PluginProcessRequestSchema: z.ZodType<PluginProcessRequest>;
+export declare const PluginProcessMessageSchema: z.ZodType<PluginProcessMessage>;
+//# sourceMappingURL=plugin-process-protocol.d.ts.map

package/dist/server/server/plugins/plugin-process-protocol.js

@@ -0,0 +1,154 @@
+import { ProviderEventSchema, ProviderInputSchema } from "@camerontaylor/paseo-plugin/server/provider";
+import { z } from "zod";
+const hooksSchema = z.object({ events: z.array(z.string()), before: z.array(z.string()) }).strict();
+const providerMetadataSchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    description: z.string().optional(),
+    iconPath: z.string().optional(),
+    hasCatalogCacheKey: z.boolean().optional(),
+})
+    .strict();
+const providerConnectRequestSchema = z
+    .object({
+    versions: z.array(z.number().int().positive()),
+    capabilities: z.array(z.string()),
+})
+    .strict();
+const frameFields = {
+    data: z.union([z.string(), z.instanceof(Uint8Array)]),
+    isBinary: z.boolean(),
+};
+export const PluginProcessRequestSchema = z.discriminatedUnion("type", [
+    z
+        .object({
+        type: z.literal("initialize"),
+        pluginId: z.string().min(1),
+        bundle: z.string(),
+        appVersion: z.string(),
+        settingsDirectory: z.string().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("provider.catalog_key"),
+        requestId: z.string().min(1),
+        providerId: z.string().min(1),
+        options: z.discriminatedUnion("scope", [
+            z.object({ scope: z.literal("global"), force: z.boolean().optional() }).strict(),
+            z
+                .object({
+                scope: z.literal("workspace"),
+                cwd: z.string(),
+                force: z.boolean().optional(),
+            })
+                .strict(),
+        ]),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("hook"),
+        requestId: z.string(),
+        kind: z.enum(["event", "before"]),
+        name: z.string(),
+        input: z.unknown(),
+    })
+        .strict(),
+    z.object({ type: z.literal("hook.cancel"), requestId: z.string() }).strict(),
+    z
+        .object({
+        type: z.literal("invoke"),
+        requestId: z.string().min(1),
+        method: z.string().min(1),
+        input: z.unknown(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("provider.connect"),
+        providerId: z.string().min(1),
+        connectionId: z.string().min(1),
+        request: providerConnectRequestSchema,
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("provider.send"),
+        connectionId: z.string().min(1),
+        acceptanceId: z.string().min(1),
+        input: ProviderInputSchema,
+    })
+        .strict(),
+    z.object({ type: z.literal("provider.close"), connectionId: z.string().min(1) }).strict(),
+    z.object({ type: z.literal("shutdown") }).strict(),
+    z.object({ type: z.literal("paseo_frame"), ...frameFields }).strict(),
+    z.object({ type: z.literal("paseo_close") }).strict(),
+]);
+export const PluginProcessMessageSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("settings.changed"), settingsId: z.string() }).strict(),
+    z.object({ type: z.literal("hooks.changed"), hooks: hooksSchema }).strict(),
+    z
+        .object({
+        type: z.literal("ready"),
+        methods: z.array(z.string()),
+        providers: z.array(providerMetadataSchema),
+        hooks: hooksSchema.optional(),
+    })
+        .strict(),
+    z
+        .object({ type: z.literal("result"), requestId: z.string().min(1), output: z.unknown() })
+        .strict(),
+    z
+        .object({ type: z.literal("error"), requestId: z.string().min(1), error: z.string() })
+        .strict(),
+    z.object({ type: z.literal("fatal"), error: z.string() }).strict(),
+    z
+        .object({
+        type: z.literal("provider.connected"),
+        connectionId: z.string().min(1),
+        version: z.number().int().positive(),
+        capabilities: z.array(z.string()),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("provider.connect_failed"),
+        connectionId: z.string().min(1),
+        error: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("provider.accepted"),
+        connectionId: z.string().min(1),
+        acceptanceId: z.string().min(1),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("provider.rejected"),
+        connectionId: z.string().min(1),
+        acceptanceId: z.string().min(1),
+        error: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("provider.event"),
+        connectionId: z.string().min(1),
+        event: ProviderEventSchema,
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("provider.closed"),
+        connectionId: z.string().min(1),
+        error: z.string().optional(),
+    })
+        .strict(),
+    z.object({ type: z.literal("paseo_frame"), ...frameFields }).strict(),
+    z.object({ type: z.literal("paseo_close") }).strict(),
+]);
+//# sourceMappingURL=plugin-process-protocol.js.map

package/dist/server/server/plugins/plugin-process.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin-process.d.ts.map

package/dist/server/server/plugins/plugin-process.js

@@ -0,0 +1,419 @@
+import { PluginHookHandlers } from "./lifecycle/index.js";
+import { PluginProcessRequestSchema, } from "./plugin-process-protocol.js";
+import { createRequire } from "node:module";
+import * as pluginSharedRuntime from "@camerontaylor/paseo-plugin";
+import * as pluginProviderRuntime from "@camerontaylor/paseo-plugin/server/provider";
+import * as pluginAcpRuntime from "@camerontaylor/paseo-plugin/server/acp";
+import { ProviderEventSchema, } from "@camerontaylor/paseo-plugin/server/provider";
+import { createPaseoApi } from "@camerontaylor/paseo-client";
+import { DaemonClient } from "@camerontaylor/paseo-client/internal/daemon-client";
+import { createPluginDaemonTransportFactory } from "./daemon-transport.js";
+import { isPluginClientOnlySdkSpecifier } from "./plugin-sdk-specifiers.js";
+import { createPluginClientId } from "./plugin-session-identity.js";
+import { PluginSettingsStore } from "./settings/index.js";
+let settingsStore = null;
+function registerSettings(definition) {
+    if (!settingsStore)
+        throw new Error("Plugin settings storage is unavailable");
+    const handlers = settingsStore.register(definition);
+    register(handlers.read.contract, handlers.read.handle);
+    register(handlers.write.contract, (input) => handlers.write.handle(handlers.write.contract.input.parse(input)));
+    register(handlers.reset.contract, (input) => handlers.reset.handle(handlers.reset.contract.input.parse(input)));
+}
+const hooks = new PluginHookHandlers(() => {
+    send({ type: "hooks.changed", hooks: hooks.catalog() });
+});
+const handlers = new Map();
+const providers = new Map();
+const providerConnections = new Map();
+const pendingProviderConnections = new Map();
+let cleanup = null;
+let daemonClient = null;
+let paseo = null;
+let stopping = false;
+const nodeRequire = createRequire(import.meta.url);
+function send(message) {
+    process.send?.(message);
+}
+function sendAndWait(message) {
+    return new Promise((resolve) => {
+        if (!process.send) {
+            resolve();
+            return;
+        }
+        process.send(message, () => resolve());
+    });
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function jsonTransportValue(value) {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new Error("Provider value is not JSON-serializable");
+    return JSON.parse(encoded);
+}
+function validateMethod(method) {
+    const normalized = method.trim();
+    if (!/^[a-z][a-z0-9._-]*$/.test(normalized)) {
+        throw new Error(`Invalid plugin RPC method: ${method}`);
+    }
+    if (handlers.has(normalized)) {
+        throw new Error(`Duplicate plugin RPC method: ${normalized}`);
+    }
+    return normalized;
+}
+function register(contract, handler) {
+    if (typeof handler !== "function") {
+        throw new Error(`Plugin RPC ${contract.name} must provide a handler`);
+    }
+    const method = validateMethod(contract.name);
+    handlers.set(method, { contract: { ...contract, name: method }, handler });
+}
+function registerProvider(provider) {
+    const id = provider.id.trim();
+    if (!/^[a-z][a-z0-9._-]*$/.test(id)) {
+        throw new Error(`Invalid plugin provider ID: ${provider.id}`);
+    }
+    if (!provider.label.trim())
+        throw new Error(`Plugin provider ${id} requires a label`);
+    if (typeof provider.connect !== "function") {
+        throw new Error(`Plugin provider ${id} must implement connect()`);
+    }
+    if (provider.getCatalogCacheKey !== undefined &&
+        typeof provider.getCatalogCacheKey !== "function") {
+        throw new Error(`Invalid catalogue key callback for plugin provider ${id}`);
+    }
+    if (providers.has(id))
+        throw new Error(`Duplicate plugin provider ID: ${id}`);
+    providers.set(id, { ...provider, id });
+}
+function providerMetadata(provider) {
+    return {
+        id: provider.id,
+        label: provider.label,
+        description: provider.description,
+        iconPath: provider.icon,
+        hasCatalogCacheKey: provider.getCatalogCacheKey !== undefined,
+    };
+}
+async function connectProvider(message) {
+    if (stopping)
+        throw new Error("Plugin is stopping");
+    const provider = providers.get(message.providerId);
+    if (!provider)
+        throw new Error(`Unknown plugin provider: ${message.providerId}`);
+    if (providerConnections.has(message.connectionId) ||
+        pendingProviderConnections.has(message.connectionId)) {
+        throw new Error(`Duplicate provider connection: ${message.connectionId}`);
+    }
+    const pending = { tombstoned: false };
+    pendingProviderConnections.set(message.connectionId, pending);
+    let connection;
+    try {
+        connection = await provider.connect(message.request);
+    }
+    catch (error) {
+        pendingProviderConnections.delete(message.connectionId);
+        if (pending.tombstoned || stopping)
+            return;
+        throw error;
+    }
+    pendingProviderConnections.delete(message.connectionId);
+    if (pending.tombstoned || stopping) {
+        await connection.close().catch(() => undefined);
+        return;
+    }
+    let unsubscribe = () => { };
+    unsubscribe = connection.onEvent((event) => {
+        try {
+            send({
+                type: "provider.event",
+                connectionId: message.connectionId,
+                event: ProviderEventSchema.parse(jsonTransportValue(event)),
+            });
+        }
+        catch (error) {
+            providerConnections.delete(message.connectionId);
+            unsubscribe();
+            void connection.close().catch(() => undefined);
+            send({
+                type: "provider.closed",
+                connectionId: message.connectionId,
+                error: describeError(error),
+            });
+        }
+    });
+    providerConnections.set(message.connectionId, { connection, unsubscribe });
+    send({
+        type: "provider.connected",
+        connectionId: message.connectionId,
+        version: connection.version,
+        capabilities: connection.capabilities,
+    });
+}
+async function sendProviderInput(message) {
+    if (stopping)
+        throw new Error("Plugin is stopping");
+    const current = providerConnections.get(message.connectionId);
+    if (!current)
+        throw new Error(`Unknown provider connection: ${message.connectionId}`);
+    await current.connection.send(message.input);
+    send({
+        type: "provider.accepted",
+        connectionId: message.connectionId,
+        acceptanceId: message.acceptanceId,
+    });
+}
+async function closeProviderConnection(connectionId) {
+    const current = providerConnections.get(connectionId);
+    if (!current)
+        return;
+    providerConnections.delete(connectionId);
+    current.unsubscribe();
+    await current.connection.close();
+    send({ type: "provider.closed", connectionId });
+}
+function runtimeRequire(name) {
+    if (isPluginClientOnlySdkSpecifier(name)) {
+        throw new Error(`${name} is available only in plugin client code`);
+    }
+    if (name === "@camerontaylor/paseo-plugin")
+        return pluginSharedRuntime;
+    if (name === "@camerontaylor/paseo-plugin/server")
+        return {};
+    if (name === "@camerontaylor/paseo-plugin/server/provider")
+        return pluginProviderRuntime;
+    if (name === "@camerontaylor/paseo-plugin/server/acp")
+        return pluginAcpRuntime;
+    if (name === "@camerontaylor/paseo-plugin/client/host")
+        throw new Error(`${name} is private to the app host`);
+    return nodeRequire(name);
+}
+function evaluateBundle(bundle) {
+    const evaluate = globalThis.eval;
+    const factory = evaluate(bundle);
+    if (typeof factory !== "function")
+        throw new Error("Plugin server bundle is not executable");
+    const exports = factory(runtimeRequire);
+    const setup = exports !== null && typeof exports === "object" ? Reflect.get(exports, "default") : undefined;
+    if (typeof setup !== "function") {
+        throw new Error("Plugin server bundle must default export a function");
+    }
+    const contributedCleanup = setup({
+        handle: register,
+        registerProvider,
+        registerSettings,
+        on: hooks.on,
+        before: hooks.before,
+    });
+    if (typeof contributedCleanup !== "function") {
+        throw new Error("Plugin contribution must return a cleanup function");
+    }
+    cleanup = contributedCleanup;
+}
+const transportFactory = createPluginDaemonTransportFactory({
+    send,
+    onMessage(handler) {
+        process.on("message", handler);
+        return () => process.off("message", handler);
+    },
+});
+async function initialize(message) {
+    daemonClient = new DaemonClient({
+        url: `ipc://plugin/${encodeURIComponent(message.pluginId)}`,
+        clientId: createPluginClientId(message.pluginId),
+        clientType: "cli",
+        appVersion: message.appVersion,
+        reconnect: { enabled: false },
+        transportFactory,
+    });
+    paseo = createPaseoApi(daemonClient);
+    await daemonClient.connect();
+    settingsStore = message.settingsDirectory
+        ? new PluginSettingsStore(message.settingsDirectory, (settingsId) => send({ type: "settings.changed", settingsId }))
+        : null;
+    evaluateBundle(message.bundle);
+    send({
+        type: "ready",
+        methods: [...handlers.keys()].sort(),
+        hooks: hooks.catalog(),
+        providers: [...providers.values()]
+            .sort((left, right) => left.id.localeCompare(right.id))
+            .map(providerMetadata),
+    });
+}
+async function shutdown() {
+    if (stopping)
+        return;
+    stopping = true;
+    hooks.close();
+    for (const pending of pendingProviderConnections.values())
+        pending.tombstoned = true;
+    const currentCleanup = cleanup;
+    cleanup = null;
+    try {
+        await currentCleanup?.();
+    }
+    catch (error) {
+        console.error("Plugin cleanup failed", error);
+    }
+    await Promise.all([...providerConnections.keys()].map(closeProviderConnection));
+    await daemonClient?.close().catch(() => undefined);
+    await sendAndWait({ type: "paseo_close" });
+    daemonClient = null;
+    paseo = null;
+    process.disconnect();
+}
+process.on("message", (rawMessage) => {
+    const parsed = PluginProcessRequestSchema.safeParse(rawMessage);
+    if (!parsed.success) {
+        const value = rawMessage;
+        if (value && typeof value.connectionId === "string" && typeof value.acceptanceId === "string") {
+            send({
+                type: "provider.rejected",
+                connectionId: value.connectionId,
+                acceptanceId: value.acceptanceId,
+                error: `Invalid provider input: ${parsed.error.message}`,
+            });
+            void closeProviderConnection(value.connectionId);
+            return;
+        }
+        send({ type: "fatal", error: `Invalid plugin process request: ${parsed.error.message}` });
+        void shutdown();
+        return;
+    }
+    const message = parsed.data;
+    if (message.type === "initialize") {
+        void initialize(message).catch(async (error) => {
+            send({ type: "fatal", error: describeError(error) });
+            await daemonClient?.close().catch(() => undefined);
+        });
+        return;
+    }
+    if (message.type === "shutdown") {
+        void shutdown();
+        return;
+    }
+    if (stopping) {
+        if (message.type === "provider.catalog_key") {
+            send({ type: "error", requestId: message.requestId, error: "Plugin is stopping" });
+        }
+        else if (message.type === "provider.connect") {
+            send({
+                type: "provider.connect_failed",
+                connectionId: message.connectionId,
+                error: "Plugin is stopping",
+            });
+        }
+        else if (message.type === "provider.send") {
+            send({
+                type: "provider.rejected",
+                connectionId: message.connectionId,
+                acceptanceId: message.acceptanceId,
+                error: "Plugin is stopping",
+            });
+        }
+        else if (message.type === "provider.close") {
+            send({ type: "provider.closed", connectionId: message.connectionId });
+        }
+        return;
+    }
+    if (message.type === "provider.catalog_key") {
+        void (async () => {
+            const provider = providers.get(message.providerId);
+            if (!provider)
+                throw new Error(`Unknown provider: ${message.providerId}`);
+            const output = await provider.getCatalogCacheKey?.(message.options);
+            if (output !== undefined && typeof output !== "string")
+                throw new Error("Invalid catalogue key");
+            send({ type: "result", requestId: message.requestId, output });
+        })().catch((error) => send({ type: "error", requestId: message.requestId, error: describeError(error) }));
+        return;
+    }
+    if (message.type === "provider.connect") {
+        void connectProvider(message).catch((error) => {
+            if (stopping)
+                return;
+            send({
+                type: "provider.connect_failed",
+                connectionId: message.connectionId,
+                error: describeError(error),
+            });
+        });
+        return;
+    }
+    if (message.type === "provider.send") {
+        void sendProviderInput(message).catch((error) => {
+            if (stopping)
+                return;
+            send({
+                type: "provider.rejected",
+                connectionId: message.connectionId,
+                acceptanceId: message.acceptanceId,
+                error: describeError(error),
+            });
+        });
+        return;
+    }
+    if (message.type === "provider.close") {
+        void closeProviderConnection(message.connectionId).catch((error) => {
+            send({
+                type: "provider.closed",
+                connectionId: message.connectionId,
+                error: describeError(error),
+            });
+        });
+        return;
+    }
+    if (message.type === "paseo_frame" || message.type === "paseo_close")
+        return;
+    if (isHookMessage(message)) {
+        handleHookMessage(message);
+        return;
+    }
+    const registered = handlers.get(message.method);
+    if (!registered) {
+        send({
+            type: "error",
+            requestId: message.requestId,
+            error: `Unknown RPC method: ${message.method}`,
+        });
+        return;
+    }
+    void registered.contract.input
+        .parseAsync(message.input)
+        .then((input) => {
+        if (!paseo)
+            throw new Error("Plugin Paseo API is unavailable");
+        return registered.handler(input, { paseo });
+    })
+        .then((output) => registered.contract.output.parseAsync(output))
+        .then((output) => send({ type: "result", requestId: message.requestId, output }), (error) => send({ type: "error", requestId: message.requestId, error: describeError(error) }));
+});
+function handleHookMessage(message) {
+    if (message.type === "hook.cancel") {
+        hooks.cancel(message.requestId);
+        return;
+    }
+    if (message.type === "hook") {
+        if (!paseo) {
+            send({
+                type: "error",
+                requestId: message.requestId,
+                error: "Plugin Paseo API is unavailable",
+            });
+            return;
+        }
+        void hooks.invoke(message.requestId, message.kind, message.name, message.input, paseo).then((output) => {
+            return send({ type: "result", requestId: message.requestId, output });
+        }, (error) => {
+            return send({ type: "error", requestId: message.requestId, error: describeError(error) });
+        });
+        return;
+    }
+}
+function isHookMessage(message) {
+    return message.type === "hook" || message.type === "hook.cancel";
+}
+//# sourceMappingURL=plugin-process.js.map

package/dist/server/server/plugins/plugin-sdk-specifiers.d.ts

@@ -0,0 +1,5 @@
+export declare const PLUGIN_CLIENT_ONLY_SDK_SPECIFIERS: readonly ["@camerontaylor/paseo-plugin/client", "@camerontaylor/paseo-plugin/client/ui", "@camerontaylor/paseo-plugin/client/react-native"];
+export declare const PLUGIN_SDK_SPECIFIERS: readonly ["@camerontaylor/paseo-plugin", "@camerontaylor/paseo-plugin/server", "@camerontaylor/paseo-plugin/server/provider", "@camerontaylor/paseo-plugin/server/acp", "@camerontaylor/paseo-plugin/client", "@camerontaylor/paseo-plugin/client/ui", "@camerontaylor/paseo-plugin/client/react-native"];
+export declare function isPluginClientOnlySdkSpecifier(name: string): boolean;
+export declare function isPluginServerOnlySdkSpecifier(name: string): boolean;
+//# sourceMappingURL=plugin-sdk-specifiers.d.ts.map