@paperclipai/plugin-sdk 2026.3.17-canary.0

package/dist/bundlers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Bundling presets for Paperclip plugins.
+ *
+ * These helpers return plain config objects so plugin authors can use them
+ * with esbuild or rollup without re-implementing host contract defaults.
+ */
+export interface PluginBundlerPresetInput {
+    pluginRoot?: string;
+    manifestEntry?: string;
+    workerEntry?: string;
+    uiEntry?: string;
+    outdir?: string;
+    sourcemap?: boolean;
+    minify?: boolean;
+}
+export interface EsbuildLikeOptions {
+    entryPoints: string[];
+    outdir: string;
+    bundle: boolean;
+    format: "esm";
+    platform: "node" | "browser";
+    target: string;
+    sourcemap?: boolean;
+    minify?: boolean;
+    external?: string[];
+}
+export interface RollupLikeConfig {
+    input: string;
+    output: {
+        dir: string;
+        format: "es";
+        sourcemap?: boolean;
+        entryFileNames?: string;
+    };
+    external?: string[];
+    plugins?: unknown[];
+}
+export interface PluginBundlerPresets {
+    esbuild: {
+        worker: EsbuildLikeOptions;
+        ui?: EsbuildLikeOptions;
+        manifest: EsbuildLikeOptions;
+    };
+    rollup: {
+        worker: RollupLikeConfig;
+        ui?: RollupLikeConfig;
+        manifest: RollupLikeConfig;
+    };
+}
+/**
+ * Build esbuild/rollup baseline configs for plugin worker, manifest, and UI bundles.
+ *
+ * The presets intentionally externalize host/runtime deps (`react`, SDK packages)
+ * to match the Paperclip plugin loader contract.
+ */
+export declare function createPluginBundlerPresets(input?: PluginBundlerPresetInput): PluginBundlerPresets;
+//# sourceMappingURL=bundlers.d.ts.map

package/dist/bundlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundlers.d.ts","sourceRoot":"","sources":["../src/bundlers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE;QACN,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,IAAI,CAAC;QACb,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE;QACP,MAAM,EAAE,kBAAkB,CAAC;QAC3B,EAAE,CAAC,EAAE,kBAAkB,CAAC;QACxB,QAAQ,EAAE,kBAAkB,CAAC;KAC9B,CAAC;IACF,MAAM,EAAE;QACN,MAAM,EAAE,gBAAgB,CAAC;QACzB,EAAE,CAAC,EAAE,gBAAgB,CAAC;QACtB,QAAQ,EAAE,gBAAgB,CAAC;KAC5B,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,GAAE,wBAA6B,GAAG,oBAAoB,CAmGrG"}

package/dist/bundlers.js

@@ -0,0 +1,105 @@
+/**
+ * Bundling presets for Paperclip plugins.
+ *
+ * These helpers return plain config objects so plugin authors can use them
+ * with esbuild or rollup without re-implementing host contract defaults.
+ */
+/**
+ * Build esbuild/rollup baseline configs for plugin worker, manifest, and UI bundles.
+ *
+ * The presets intentionally externalize host/runtime deps (`react`, SDK packages)
+ * to match the Paperclip plugin loader contract.
+ */
+export function createPluginBundlerPresets(input = {}) {
+    const uiExternal = [
+        "@paperclipai/plugin-sdk/ui",
+        "@paperclipai/plugin-sdk/ui/hooks",
+        "react",
+        "react-dom",
+        "react/jsx-runtime",
+    ];
+    const outdir = input.outdir ?? "dist";
+    const workerEntry = input.workerEntry ?? "src/worker.ts";
+    const manifestEntry = input.manifestEntry ?? "src/manifest.ts";
+    const uiEntry = input.uiEntry;
+    const sourcemap = input.sourcemap ?? true;
+    const minify = input.minify ?? false;
+    const esbuildWorker = {
+        entryPoints: [workerEntry],
+        outdir,
+        bundle: true,
+        format: "esm",
+        platform: "node",
+        target: "node20",
+        sourcemap,
+        minify,
+        external: ["react", "react-dom"],
+    };
+    const esbuildManifest = {
+        entryPoints: [manifestEntry],
+        outdir,
+        bundle: false,
+        format: "esm",
+        platform: "node",
+        target: "node20",
+        sourcemap,
+    };
+    const esbuildUi = uiEntry
+        ? {
+            entryPoints: [uiEntry],
+            outdir: `${outdir}/ui`,
+            bundle: true,
+            format: "esm",
+            platform: "browser",
+            target: "es2022",
+            sourcemap,
+            minify,
+            external: uiExternal,
+        }
+        : undefined;
+    const rollupWorker = {
+        input: workerEntry,
+        output: {
+            dir: outdir,
+            format: "es",
+            sourcemap,
+            entryFileNames: "worker.js",
+        },
+        external: ["react", "react-dom"],
+    };
+    const rollupManifest = {
+        input: manifestEntry,
+        output: {
+            dir: outdir,
+            format: "es",
+            sourcemap,
+            entryFileNames: "manifest.js",
+        },
+        external: ["@paperclipai/plugin-sdk"],
+    };
+    const rollupUi = uiEntry
+        ? {
+            input: uiEntry,
+            output: {
+                dir: `${outdir}/ui`,
+                format: "es",
+                sourcemap,
+                entryFileNames: "index.js",
+            },
+            external: uiExternal,
+        }
+        : undefined;
+    return {
+        esbuild: {
+            worker: esbuildWorker,
+            manifest: esbuildManifest,
+            ...(esbuildUi ? { ui: esbuildUi } : {}),
+        },
+        rollup: {
+            worker: rollupWorker,
+            manifest: rollupManifest,
+            ...(rollupUi ? { ui: rollupUi } : {}),
+        },
+    };
+}
+//# sourceMappingURL=bundlers.js.map

package/dist/bundlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundlers.js","sourceRoot":"","sources":["../src/bundlers.ts"],"names":[],"mappings":"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"}

package/dist/define-plugin.d.ts

@@ -0,0 +1,218 @@
+/**
+ * `definePlugin` — the top-level helper for authoring a Paperclip plugin.
+ *
+ * Plugin authors call `definePlugin()` and export the result as the default
+ * export from their worker entrypoint. The host imports the worker module,
+ * calls `setup()` with a `PluginContext`, and from that point the plugin
+ * responds to events, jobs, webhooks, and UI requests through the context.
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ *
+ * @example
+ * ```ts
+ * // dist/worker.ts
+ * import { definePlugin } from "@paperclipai/plugin-sdk";
+ *
+ * export default definePlugin({
+ *   async setup(ctx) {
+ *     ctx.logger.info("Linear sync plugin starting");
+ *
+ *     // Subscribe to events
+ *     ctx.events.on("issue.created", async (event) => {
+ *       const config = await ctx.config.get();
+ *       await ctx.http.fetch(`https://api.linear.app/...`, {
+ *         method: "POST",
+ *         headers: { Authorization: `Bearer ${await ctx.secrets.resolve(config.apiKeyRef as string)}` },
+ *         body: JSON.stringify({ title: event.payload.title }),
+ *       });
+ *     });
+ *
+ *     // Register a job handler
+ *     ctx.jobs.register("full-sync", async (job) => {
+ *       ctx.logger.info("Running full-sync job", { runId: job.runId });
+ *       // ... sync logic
+ *     });
+ *
+ *     // Register data for the UI
+ *     ctx.data.register("sync-health", async ({ companyId }) => {
+ *       const state = await ctx.state.get({
+ *         scopeKind: "company",
+ *         scopeId: String(companyId),
+ *         stateKey: "last-sync",
+ *       });
+ *       return { lastSync: state };
+ *     });
+ *   },
+ * });
+ * ```
+ */
+import type { PluginContext } from "./types.js";
+/**
+ * Optional plugin-reported diagnostics returned from the `health()` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.2 — `health`
+ */
+export interface PluginHealthDiagnostics {
+    /** Machine-readable status: `"ok"` | `"degraded"` | `"error"`. */
+    status: "ok" | "degraded" | "error";
+    /** Human-readable description of the current health state. */
+    message?: string;
+    /** Plugin-reported key-value diagnostics (e.g. connection status, queue depth). */
+    details?: Record<string, unknown>;
+}
+/**
+ * Result returned from the `validateConfig()` RPC method.
+ *
+ * @see PLUGIN_SPEC.md §13.3 — `validateConfig`
+ */
+export interface PluginConfigValidationResult {
+    /** Whether the config is valid. */
+    ok: boolean;
+    /** Non-fatal warnings about the config. */
+    warnings?: string[];
+    /** Validation errors (populated when `ok` is `false`). */
+    errors?: string[];
+}
+/**
+ * Input received by the plugin worker's `handleWebhook` handler.
+ *
+ * @see PLUGIN_SPEC.md §13.7 — `handleWebhook`
+ */
+export interface PluginWebhookInput {
+    /** Endpoint key matching the manifest declaration. */
+    endpointKey: string;
+    /** Inbound request headers. */
+    headers: Record<string, string | string[]>;
+    /** Raw request body as a UTF-8 string. */
+    rawBody: string;
+    /** Parsed JSON body (if applicable and parseable). */
+    parsedBody?: unknown;
+    /** Unique request identifier for idempotency checks. */
+    requestId: string;
+}
+/**
+ * The plugin definition shape passed to `definePlugin()`.
+ *
+ * The only required field is `setup`, which receives the `PluginContext` and
+ * is where the plugin registers its handlers (events, jobs, data, actions,
+ * tools, etc.).
+ *
+ * All other lifecycle hooks are optional. If a hook is not implemented the
+ * host applies default behaviour (e.g. restarting the worker on config change
+ * instead of calling `onConfigChanged`).
+ *
+ * @see PLUGIN_SPEC.md §13 — Host-Worker Protocol
+ */
+export interface PluginDefinition {
+    /**
+     * Called once when the plugin worker starts up, after `initialize` completes.
+     *
+     * This is where the plugin registers all its handlers: event subscriptions,
+     * job handlers, data/action handlers, and tool registrations. Registration
+     * must be synchronous after `setup` resolves — do not register handlers
+     * inside async callbacks that may resolve after `setup` returns.
+     *
+     * @param ctx - The full plugin context provided by the host
+     */
+    setup(ctx: PluginContext): Promise<void>;
+    /**
+     * Called when the host wants to know if the plugin is healthy.
+     *
+     * The host polls this on a regular interval and surfaces the result in the
+     * plugin health dashboard. If not implemented, the host infers health from
+     * worker process liveness.
+     *
+     * @see PLUGIN_SPEC.md §13.2 — `health`
+     */
+    onHealth?(): Promise<PluginHealthDiagnostics>;
+    /**
+     * Called when the operator updates the plugin's instance configuration at
+     * runtime, without restarting the worker.
+     *
+     * If not implemented, the host restarts the worker to apply the new config.
+     *
+     * @param newConfig - The newly resolved configuration
+     * @see PLUGIN_SPEC.md §13.4 — `configChanged`
+     */
+    onConfigChanged?(newConfig: Record<string, unknown>): Promise<void>;
+    /**
+     * Called when the host is about to shut down the plugin worker.
+     *
+     * The worker has at most 10 seconds (configurable via plugin config) to
+     * finish in-flight work and resolve this promise. After the deadline the
+     * host sends SIGTERM, then SIGKILL.
+     *
+     * @see PLUGIN_SPEC.md §12.5 — Graceful Shutdown Policy
+     */
+    onShutdown?(): Promise<void>;
+    /**
+     * Called to validate the current plugin configuration.
+     *
+     * The host calls this:
+     * - after the plugin starts (to surface config errors immediately)
+     * - after the operator saves a new config (to validate before persisting)
+     * - via the "Test Connection" button in the settings UI
+     *
+     * @param config - The configuration to validate
+     * @see PLUGIN_SPEC.md §13.3 — `validateConfig`
+     */
+    onValidateConfig?(config: Record<string, unknown>): Promise<PluginConfigValidationResult>;
+    /**
+     * Called to handle an inbound webhook delivery.
+     *
+     * The host routes `POST /api/plugins/:pluginId/webhooks/:endpointKey` to
+     * this handler. The plugin is responsible for signature verification using
+     * a resolved secret ref.
+     *
+     * If not implemented but webhooks are declared in the manifest, the host
+     * returns HTTP 501 for webhook deliveries.
+     *
+     * @param input - Webhook delivery metadata and payload
+     * @see PLUGIN_SPEC.md §13.7 — `handleWebhook`
+     */
+    onWebhook?(input: PluginWebhookInput): Promise<void>;
+}
+/**
+ * The sealed plugin object returned by `definePlugin()`.
+ *
+ * Plugin authors export this as the default export from their worker
+ * entrypoint. The host imports it and calls the lifecycle methods.
+ *
+ * @see PLUGIN_SPEC.md §14 — SDK Surface
+ */
+export interface PaperclipPlugin {
+    /** The original plugin definition passed to `definePlugin()`. */
+    readonly definition: PluginDefinition;
+}
+/**
+ * Define a Paperclip plugin.
+ *
+ * Call this function in your worker entrypoint and export the result as the
+ * default export. The host will import the module and call lifecycle methods
+ * on the returned object.
+ *
+ * @param definition - Plugin lifecycle handlers
+ * @returns A sealed `PaperclipPlugin` object for the host to consume
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from "@paperclipai/plugin-sdk";
+ *
+ * export default definePlugin({
+ *   async setup(ctx) {
+ *     ctx.logger.info("Plugin started");
+ *     ctx.events.on("issue.created", async (event) => {
+ *       // handle event
+ *     });
+ *   },
+ *
+ *   async onHealth() {
+ *     return { status: "ok" };
+ *   },
+ * });
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ */
+export declare function definePlugin(definition: PluginDefinition): PaperclipPlugin;
+//# sourceMappingURL=define-plugin.d.ts.map

package/dist/define-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-plugin.d.ts","sourceRoot":"","sources":["../src/define-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,kEAAkE;IAClE,MAAM,EAAE,IAAI,GAAG,UAAU,GAAG,OAAO,CAAC;IACpC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAMD;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,mCAAmC;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC3C,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAE9C;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IAE1F;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;CACvC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,gBAAgB,GAAG,eAAe,CAE1E"}

package/dist/define-plugin.js

@@ -0,0 +1,85 @@
+/**
+ * `definePlugin` — the top-level helper for authoring a Paperclip plugin.
+ *
+ * Plugin authors call `definePlugin()` and export the result as the default
+ * export from their worker entrypoint. The host imports the worker module,
+ * calls `setup()` with a `PluginContext`, and from that point the plugin
+ * responds to events, jobs, webhooks, and UI requests through the context.
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ *
+ * @example
+ * ```ts
+ * // dist/worker.ts
+ * import { definePlugin } from "@paperclipai/plugin-sdk";
+ *
+ * export default definePlugin({
+ *   async setup(ctx) {
+ *     ctx.logger.info("Linear sync plugin starting");
+ *
+ *     // Subscribe to events
+ *     ctx.events.on("issue.created", async (event) => {
+ *       const config = await ctx.config.get();
+ *       await ctx.http.fetch(`https://api.linear.app/...`, {
+ *         method: "POST",
+ *         headers: { Authorization: `Bearer ${await ctx.secrets.resolve(config.apiKeyRef as string)}` },
+ *         body: JSON.stringify({ title: event.payload.title }),
+ *       });
+ *     });
+ *
+ *     // Register a job handler
+ *     ctx.jobs.register("full-sync", async (job) => {
+ *       ctx.logger.info("Running full-sync job", { runId: job.runId });
+ *       // ... sync logic
+ *     });
+ *
+ *     // Register data for the UI
+ *     ctx.data.register("sync-health", async ({ companyId }) => {
+ *       const state = await ctx.state.get({
+ *         scopeKind: "company",
+ *         scopeId: String(companyId),
+ *         stateKey: "last-sync",
+ *       });
+ *       return { lastSync: state };
+ *     });
+ *   },
+ * });
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// definePlugin — top-level factory
+// ---------------------------------------------------------------------------
+/**
+ * Define a Paperclip plugin.
+ *
+ * Call this function in your worker entrypoint and export the result as the
+ * default export. The host will import the module and call lifecycle methods
+ * on the returned object.
+ *
+ * @param definition - Plugin lifecycle handlers
+ * @returns A sealed `PaperclipPlugin` object for the host to consume
+ *
+ * @example
+ * ```ts
+ * import { definePlugin } from "@paperclipai/plugin-sdk";
+ *
+ * export default definePlugin({
+ *   async setup(ctx) {
+ *     ctx.logger.info("Plugin started");
+ *     ctx.events.on("issue.created", async (event) => {
+ *       // handle event
+ *     });
+ *   },
+ *
+ *   async onHealth() {
+ *     return { status: "ok" };
+ *   },
+ * });
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §14.1 — Example SDK Shape
+ */
+export function definePlugin(definition) {
+    return Object.freeze({ definition });
+}
+//# sourceMappingURL=define-plugin.js.map

package/dist/define-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-plugin.js","sourceRoot":"","sources":["../src/define-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AA2KH,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,YAAY,CAAC,UAA4B;IACvD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;AACvC,CAAC"}

package/dist/dev-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=dev-cli.d.ts.map

package/dist/dev-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-cli.d.ts","sourceRoot":"","sources":["../src/dev-cli.ts"],"names":[],"mappings":""}

package/dist/dev-cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { startPluginDevServer } from "./dev-server.js";
+function parseArg(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index < 0)
+        return undefined;
+    return process.argv[index + 1];
+}
+/**
+ * CLI entrypoint for the local plugin UI preview server.
+ *
+ * This is intentionally minimal and delegates all serving behavior to
+ * `startPluginDevServer` so tests and programmatic usage share one path.
+ */
+async function main() {
+    const rootDir = parseArg("--root") ?? process.cwd();
+    const uiDir = parseArg("--ui-dir") ?? "dist/ui";
+    const host = parseArg("--host") ?? "127.0.0.1";
+    const rawPort = parseArg("--port") ?? "4177";
+    const port = Number.parseInt(rawPort, 10);
+    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+        throw new Error(`Invalid --port value: ${rawPort}`);
+    }
+    const server = await startPluginDevServer({
+        rootDir: path.resolve(rootDir),
+        uiDir,
+        host,
+        port,
+    });
+    // eslint-disable-next-line no-console
+    console.log(`Paperclip plugin dev server listening at ${server.url}`);
+    const shutdown = async () => {
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", () => {
+        void shutdown();
+    });
+    process.on("SIGTERM", () => {
+        void shutdown();
+    });
+}
+void main().catch((error) => {
+    // eslint-disable-next-line no-console
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
+//# sourceMappingURL=dev-cli.js.map

package/dist/dev-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-cli.js","sourceRoot":"","sources":["../src/dev-cli.ts"],"names":[],"mappings":";AACA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAChC,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACpD,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,SAAS,CAAC;IAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,WAAW,CAAC;IAC/C,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC;QACxC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;QAC9B,KAAK;QACL,IAAI;QACJ,IAAI;KACL,CAAC,CAAC;IAEH,sCAAsC;IACtC,OAAO,CAAC,GAAG,CAAC,4CAA4C,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAEtE,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC1B,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/dev-server.d.ts

@@ -0,0 +1,34 @@
+export interface PluginDevServerOptions {
+    /** Plugin project root. Defaults to `process.cwd()`. */
+    rootDir?: string;
+    /** Relative path from root to built UI assets. Defaults to `dist/ui`. */
+    uiDir?: string;
+    /** Bind port for local preview server. Defaults to `4177`. */
+    port?: number;
+    /** Bind host. Defaults to `127.0.0.1`. */
+    host?: string;
+}
+export interface PluginDevServer {
+    url: string;
+    close(): Promise<void>;
+}
+/**
+ * Start a local static server for plugin UI assets with SSE reload events.
+ *
+ * Endpoint summary:
+ * - `GET /__paperclip__/health` for diagnostics
+ * - `GET /__paperclip__/events` for hot-reload stream
+ * - Any other path serves files from the configured UI build directory
+ */
+export declare function startPluginDevServer(options?: PluginDevServerOptions): Promise<PluginDevServer>;
+/**
+ * Return a stable file+mtime snapshot for a built plugin UI directory.
+ *
+ * Used by the polling watcher fallback and useful for tests that need to assert
+ * whether a UI build has changed between runs.
+ */
+export declare function getUiBuildSnapshot(rootDir: string, uiDir?: string): Promise<Array<{
+    file: string;
+    mtimeMs: number;
+}>>;
+//# sourceMappingURL=dev-server.d.ts.map

package/dist/dev-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../src/dev-server.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAkGD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,eAAe,CAAC,CAiFzG;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAY,GAAG,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAY9H"}