Skip to content

The open-source app everyone uses to manage agents at work

[codex] Improve local plugin development workflow (#5821)

Dottab947a7d76c33
diff --git a/cli/src/__tests__/plugin-init.test.ts b/cli/src/__tests__/plugin-init.test.ts
new file mode 100644
index 0000000000..8faeb4592f
--- /dev/null
+++ b/cli/src/__tests__/plugin-init.test.ts
@@ -0,0 +1,164 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ scaffoldPluginProject: vi.fn((options: { outputDir: string }) => options.outputDir),
+}));
+
+vi.mock("../../../packages/plugins/create-paperclip-plugin/src/index.js", async () => {
+ const actual =
+ await vi.importActual<typeof import("../../../packages/plugins/create-paperclip-plugin/src/index.js")>(
+ "../../../packages/plugins/create-paperclip-plugin/src/index.js",
+ );
+ return {
+ ...actual,
+ scaffoldPluginProject: mocks.scaffoldPluginProject,
+ };
+});
+
+import {
+ buildPluginInstallRequest,
+ buildPluginInitNextCommands,
+ buildPluginInitScaffoldOptions,
+ registerPluginCommands,
+} from "../commands/client/plugin.js";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cli-plugin-"));
+ tempDirs.push(dir);
+ return dir;
+}
+
+afterEach(() => {
+ while (tempDirs.length > 0) {
+ const dir = tempDirs.pop();
+ if (dir) fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+describe("plugin init", () => {
+ beforeEach(() => {
+ mocks.scaffoldPluginProject.mockClear();
+ });
+
+ it("maps package name and flags to scaffolder options", () => {
+ const cwd = path.resolve("/tmp/paperclip-cli-test");
+ const options = buildPluginInitScaffoldOptions(
+ "@acme/plugin-linear",
+ {
+ output: "plugins",
+ template: "connector",
+ category: "automation",
+ displayName: "Linear Bridge",
+ description: "Syncs Linear issues",
+ author: "Acme",
+ sdkPath: "../paperclip/packages/plugins/sdk",
+ },
+ cwd,
+ );
+
+ expect(options).toEqual({
+ pluginName: "@acme/plugin-linear",
+ outputDir: path.resolve(cwd, "plugins", "plugin-linear"),
+ template: "connector",
+ category: "automation",
+ displayName: "Linear Bridge",
+ description: "Syncs Linear issues",
+ author: "Acme",
+ sdkPath: "../paperclip/packages/plugins/sdk",
+ });
+ });
+
+ it("builds exact next commands using the scaffold path", () => {
+ expect(buildPluginInitNextCommands("/tmp/acme plugin")).toEqual([
+ "cd '/tmp/acme plugin'",
+ "pnpm install",
+ "pnpm dev",
+ "paperclipai plugin install '/tmp/acme plugin'",
+ ]);
+ });
+
+ it("registers the CLI wrapper and invokes the existing scaffolder", async () => {
+ const program = new Command();
+ program.exitOverride();
+ program.configureOutput({ writeOut: () => {}, writeErr: () => {} });
+ registerPluginCommands(program);
+
+ await program.parseAsync(
+ [
+ "plugin",
+ "init",
+ "demo-plugin",
+ "--output",
+ "/tmp/paperclip-init-output",
+ "--template",
+ "workspace",
+ "--category",
+ "workspace",
+ "--display-name",
+ "Demo Plugin",
+ "--description",
+ "Demo description",
+ "--author",
+ "Paperclip",
+ "--sdk-path",
+ "/repo/packages/plugins/sdk",
+ ],
+ { from: "user" },
+ );
+
+ expect(mocks.scaffoldPluginProject).toHaveBeenCalledTimes(1);
+ expect(mocks.scaffoldPluginProject).toHaveBeenCalledWith({
+ pluginName: "demo-plugin",
+ outputDir: path.resolve("/tmp/paperclip-init-output", "demo-plugin"),
+ template: "workspace",
+ category: "workspace",
+ displayName: "Demo Plugin",
+ description: "Demo description",
+ author: "Paperclip",
+ sdkPath: "/repo/packages/plugins/sdk",
+ });
+ });
+});
+
+describe("plugin install", () => {
+ it("resolves an existing relative local path to an absolute local install request", () => {
+ const cwd = makeTempDir();
+ const pluginDir = path.join(cwd, "demo-plugin");
+ fs.mkdirSync(pluginDir);
+
+ expect(buildPluginInstallRequest("demo-plugin", {}, { cwd })).toEqual({
+ packageName: pluginDir,
+ version: undefined,
+ isLocalPath: true,
+ });
+ });
+
+ it("keeps an absolute local path absolute and marks it as local", () => {
+ const pluginDir = path.join(makeTempDir(), "demo-plugin");
+ fs.mkdirSync(pluginDir);
+
+ expect(buildPluginInstallRequest(pluginDir, {}, { cwd: "/" })).toEqual({
+ packageName: pluginDir,
+ version: undefined,
+ isLocalPath: true,
+ });
+ });
+
+ it("preserves npm package installs when no local path exists", () => {
+ expect(
+ buildPluginInstallRequest("@acme/plugin-linear", { version: "1.2.3" }, {
+ cwd: makeTempDir(),
+ }),
+ ).toEqual({
+ packageName: "@acme/plugin-linear",
+ version: "1.2.3",
+ isLocalPath: false,
+ });
+ });
+});
diff --git a/cli/src/commands/client/plugin.ts b/cli/src/commands/client/plugin.ts
index 9031d696ed..933671e356 100644
--- a/cli/src/commands/client/plugin.ts
+++ b/cli/src/commands/client/plugin.ts
@@ -1,5 +1,11 @@
import path from "node:path";
-import { Command } from "commander";
+import { existsSync } from "node:fs";
+import { Command, Option } from "commander";
+import {
+ scaffoldPluginProject,
+ shellQuote,
+ type ScaffoldPluginOptions,
+} from "../../../../packages/plugins/create-paperclip-plugin/src/index.js";
import pc from "picocolors";
import {
addCommonClientOptions,
@@ -39,28 +45,101 @@ interface PluginInstallOptions extends BaseClientOptions {
version?: string;
}
+interface PluginInstallRequest {
+ packageName: string;
+ version?: string;
+ isLocalPath: boolean;
+}
+
interface PluginUninstallOptions extends BaseClientOptions {
force?: boolean;
}
+interface PluginInitOptions extends BaseClientOptions {
+ output?: string;
+ template?: ScaffoldPluginOptions["template"];
+ category?: ScaffoldPluginOptions["category"];
+ displayName?: string;
+ description?: string;
+ author?: string;
+ sdkPath?: string;
+}
+
+interface PluginInitResult {
+ outputDir: string;
+ nextCommands: string[];
+}
+
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
+function expandHomePath(packageArg: string): string {
+ if (!packageArg.startsWith("~")) return packageArg;
+ const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+ return path.resolve(home, packageArg.slice(1).replace(/^[\\/]/, ""));
+}
+
+function hasLocalPathSyntax(packageArg: string): boolean {
+ return (
+ path.isAbsolute(packageArg) ||
+ packageArg.startsWith("./") ||
+ packageArg.startsWith("../") ||
+ packageArg.startsWith("~") ||
+ packageArg.startsWith(".\\") ||
+ packageArg.startsWith("..\\")
+ );
+}
+
+function isExistingRelativePath(
+ packageArg: string,
+ cwd: string,
+ pathExists: (targetPath: string) => boolean,
+): boolean {
+ if (packageArg.trim() === "") return false;
+ if (hasLocalPathSyntax(packageArg)) return false;
+ return pathExists(path.resolve(cwd, packageArg));
+}
+
/**
* Resolve a local path argument to an absolute path so the server can find the
* plugin on disk regardless of where the user ran the CLI.
*/
-function resolvePackageArg(packageArg: string, isLocal: boolean): string {
+function resolvePackageArg(packageArg: string, isLocal: boolean, cwd = process.cwd()): string {
if (!isLocal) return packageArg;
- // Already absolute
if (path.isAbsolute(packageArg)) return packageArg;
- // Expand leading ~ to home directory
- if (packageArg.startsWith("~")) {
- const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
- return path.resolve(home, packageArg.slice(1).replace(/^[\\/]/, ""));
+ if (packageArg.startsWith("~")) return expandHomePath(packageArg);
+ return path.resolve(cwd, packageArg);
+}
+
+export function buildPluginInstallRequest(
+ packageArg: string,
+ opts: Pick<PluginInstallOptions, "local" | "version"> = {},
+ deps: { cwd?: string; existsSync?: (targetPath: string) => boolean } = {},
+): PluginInstallRequest {
+ const cwd = deps.cwd ?? process.cwd();
+ const pathExists = deps.existsSync ?? existsSync;
+ const isLocal =
+ opts.local ||
+ hasLocalPathSyntax(packageArg) ||
+ (opts.version ? false : isExistingRelativePath(packageArg, cwd, pathExists));
+
+ if (isLocal && opts.version) {
+ throw new Error("--version is only supported for npm package installs, not local plugin paths.");
}
- return path.resolve(process.cwd(), packageArg);
+
+ return {
+ packageName: resolvePackageArg(packageArg, Boolean(isLocal), cwd),
+ version: opts.version,
+ isLocalPath: Boolean(isLocal),
+ };
+}
+
+export function renderLocalPluginInstallHint(packagePath: string): string {
+ return [
+ pc.dim("Local plugin installs run trusted local code from your machine."),
+ pc.dim(`Keep ${pc.cyan("pnpm dev")} running in ${packagePath}; Paperclip watches rebuilt dist output and reloads the plugin worker.`),
+ ].join("\n");
}
function formatPlugin(p: PluginRecord): string {
@@ -87,6 +166,58 @@ function formatPlugin(p: PluginRecord): string {
return parts.join(" ");
}
+function packageToDirName(pluginName: string): string {
+ return pluginName.replace(/^@[^/]+\//, "");
+}
+
+export function buildPluginInitScaffoldOptions(
+ packageName: string,
+ opts: PluginInitOptions,
+ cwd = process.cwd(),
+): ScaffoldPluginOptions {
+ const outputRoot = path.resolve(cwd, opts.output ?? ".");
+ const outputDir = path.resolve(outputRoot, packageToDirName(packageName));
+
+ return {
+ pluginName: packageName,
+ outputDir,
+ template: opts.template,
+ category: opts.category,
+ displayName: opts.displayName,
+ description: opts.description,
+ author: opts.author,
+ sdkPath: opts.sdkPath,
+ };
+}
+
+export function buildPluginInitNextCommands(outputDir: string): string[] {
+ const quotedOutputDir = shellQuote(outputDir);
+ return [
+ `cd ${quotedOutputDir}`,
+ "pnpm install",
+ "pnpm dev",
+ `paperclipai plugin install ${quotedOutputDir}`,
+ ];
+}
+
+export function renderPluginInitSuccess(result: PluginInitResult): string {
+ return [
+ pc.green(`✓ Created plugin scaffold at ${result.outputDir}`),
+ "",
+ "Next commands:",
+ ...result.nextCommands.map((command) => ` ${pc.cyan(command)}`),
+ ].join("\n");
+}
+
+export function runPluginInitCommand(packageName: string, opts: PluginInitOptions): PluginInitResult {
+ const scaffoldOptions = buildPluginInitScaffoldOptions(packageName, opts);
+ const outputDir = scaffoldPluginProject(scaffoldOptions);
+ return {
+ outputDir,
+ nextCommands: buildPluginInitNextCommands(outputDir),
+ };
+}
+
// ---------------------------------------------------------------------------
// Command registration
// ---------------------------------------------------------------------------
@@ -94,6 +225,43 @@ function formatPlugin(p: PluginRecord): string {
export function registerPluginCommands(program: Command): void {
const plugin = program.command("plugin").description("Plugin lifecycle management");
+ // -------------------------------------------------------------------------
+ // plugin init <package-name>
+ // -------------------------------------------------------------------------
+ addCommonClientOptions(
+ plugin
+ .command("init <packageName>")
+ .description("Scaffold a local Paperclip plugin project")
+ .option("--output <dir>", "Directory to create the plugin folder in")
+ .addOption(
+ new Option("--template <template>", "Starter template")
+ .choices(["default", "connector", "workspace", "environment"])
+ .default("default"),
+ )
+ .addOption(
+ new Option("--category <category>", "Manifest category")
+ .choices(["connector", "workspace", "automation", "ui", "environment"]),
+ )
+ .option("--display-name <name>", "Manifest display name")
+ .option("--description <description>", "Manifest description")
+ .option("--author <author>", "Manifest author")
+ .option("--sdk-path <path>", "Local @paperclipai/plugin-sdk package path")
+ .action((packageName: string, opts: PluginInitOptions) => {
+ try {
+ const result = runPluginInitCommand(packageName, opts);
+
+ if (opts.json) {
+ printOutput(result, { json: true });
+ return;
+ }
+
+ console.log(renderPluginInitSuccess(result));
+ } catch (err) {
+ handleCommandError(err);
+ }
+ }),
+ );
+
// -------------------------------------------------------------------------
// plugin list
// -------------------------------------------------------------------------
@@ -147,31 +315,19 @@ export function registerPluginCommands(program: Command): void {
try {
const ctx = resolveCommandContext(opts);
- // Auto-detect local paths: starts with . or / or ~ or is an absolute path
- const isLocal =
- opts.local ||
- packageArg.startsWith("./") ||
- packageArg.startsWith("../") ||
- packageArg.startsWith("/") ||
- packageArg.startsWith("~");
-
- const resolvedPackage = resolvePackageArg(packageArg, isLocal);
+ const installRequest = buildPluginInstallRequest(packageArg, opts);
if (!ctx.json) {
console.log(
pc.dim(
- isLocal
- ? `Installing plugin from local path: ${resolvedPackage}`
- : `Installing plugin: ${resolvedPackage}${opts.version ? `@${opts.version}` : ""}`,
+ installRequest.isLocalPath
+ ? `Installing plugin from local path: ${installRequest.packageName}`
+ : `Installing plugin: ${installRequest.packageName}${opts.version ? `@${opts.version}` : ""}`,
),
);
}
- const installedPlugin = await ctx.api.post<PluginRecord>("/api/plugins/install", {
- packageName: resolvedPackage,
- version: opts.version,
- isLocalPath: isLocal,
- });
+ const installedPlugin = await ctx.api.post<PluginRecord>("/api/plugins/install", installRequest);
if (ctx.json) {
printOutput(installedPlugin, { json: true });
@@ -192,6 +348,10 @@ export function registerPluginCommands(program: Command): void {
if (installedPlugin.lastError) {
console.log(pc.red(` Warning: ${installedPlugin.lastError}`));
}
+
+ if (installRequest.isLocalPath) {
+ console.log(renderLocalPluginInstallHint(installRequest.packageName));
+ }
} catch (err) {
handleCommandError(err);
}
diff --git a/cli/tsconfig.json b/cli/tsconfig.json
index 3af05f5163..3b42fe7771 100644
--- a/cli/tsconfig.json
+++ b/cli/tsconfig.json
@@ -4,5 +4,5 @@
"outDir": "dist",
"rootDir": ".."
},
- "include": ["src", "../packages/shared/src"]
+ "include": ["src", "../packages/shared/src", "../packages/plugins/create-paperclip-plugin/src"]
}
diff --git a/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md b/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md
new file mode 100644
index 0000000000..18b033e3a2
--- /dev/null
+++ b/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md
@@ -0,0 +1,136 @@
+# Local Plugin Development
+
+This is the short happy-path guide for developing a Paperclip plugin from a folder on your machine. You will scaffold a plugin, run it in watch mode, install it into a running Paperclip instance from an absolute local path, and edit code with the plugin worker reloading after each rebuild.
+
+For the full alpha surface — manifest fields, capabilities, managed agents/projects/routines, UI slots, scoped API routes — see [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md).
+
+## Prerequisites
+
+- Node.js 22+ and `pnpm`.
+- A local Paperclip checkout you can run from source. Local plugin installs read source from disk, so the running server must be able to see the path you give it.
+
+## The five steps
+
+```bash
+# 1. Start Paperclip locally
+pnpm paperclipai run
+
+# 2. Scaffold a plugin outside the Paperclip repo
+paperclipai plugin init @acme/hello-plugin --output ~/dev/paperclip-plugins
+
+# 3. Install dependencies and start the watch build
+cd ~/dev/paperclip-plugins/hello-plugin
+pnpm install
+pnpm dev
+
+# 4. In another terminal, install the plugin from its absolute path
+paperclipai plugin install ~/dev/paperclip-plugins/hello-plugin
+
+# 5. Confirm it loaded
+paperclipai plugin list
+paperclipai plugin inspect acme.hello-plugin
+```
+
+That's the loop. The rest of this page explains what each step does and what to expect when you edit code.
+
+### 1. Start Paperclip
+
+```bash
+pnpm paperclipai run
+```
+
+Paperclip listens on `http://127.0.0.1:3100` by default. The CLI talks to that server, so leave it running.
+
+### 2. Scaffold the plugin
+
+```bash
+paperclipai plugin init @acme/hello-plugin --output ~/dev/paperclip-plugins
+```
+
+This creates `~/dev/paperclip-plugins/hello-plugin/` with `src/manifest.ts`, `src/worker.ts`, `src/ui/index.tsx`, an esbuild watch config, a Vitest config, and a snapshot of `@paperclipai/plugin-sdk` from your local Paperclip checkout. You can run the package and tests without publishing anything to npm.
+
+Useful flags:
+
+- `--template <default|connector|workspace|environment>` — starter shape.
+- `--category <connector|workspace|automation|ui|environment>` — manifest category.
+- `--display-name`, `--description`, `--author` — manifest metadata.
+- `--sdk-path <absolute-path>` — point at a specific `packages/plugins/sdk` checkout if you have more than one.
+
+When `plugin init` finishes, it prints the next four commands literally. You can copy them.
+
+### 3. Install dependencies and run the watch build
+
+```bash
+cd ~/dev/paperclip-plugins/hello-plugin
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` runs `esbuild --watch` against the plugin source and emits `dist/manifest.js`, `dist/worker.js`, and `dist/ui/`. Leave it running. Every time you save, esbuild rebuilds the affected output file.
+
+If your plugin has UI and you want a browser-side dev server with hot module replacement during local UI iteration, run `pnpm dev:ui` in a second terminal. It serves `dist/ui/` on `http://127.0.0.1:4177`. This is optional; Paperclip can load the built UI directly from `dist/ui/` without it.
+
+### 4. Install from the absolute path
+
+```bash
+paperclipai plugin install ~/dev/paperclip-plugins/hello-plugin
+```
+
+The CLI auto-detects local paths (anything that looks absolute, starts with `./`, `../`, or `~`, or resolves to an existing folder relative to the current directory) and sends `{ isLocalPath: true }` to `POST /api/plugins/install` with the resolved absolute path. If you want to be explicit, pass `--local`.
+
+You will see a confirmation like:
+
+```
+Installing plugin from local path: /Users/you/dev/paperclip-plugins/hello-plugin
+✓ Installed acme.hello-plugin v0.1.0 (ready)
+Local plugin installs run trusted local code from your machine.
+Keep `pnpm dev` running in /Users/you/dev/paperclip-plugins/hello-plugin;
+Paperclip watches rebuilt dist output and reloads the plugin worker.
+```
+
+Relative paths are resolved against the current working directory, so `paperclipai plugin install .` from inside the plugin folder works too.
+
+### 5. Inspect
+
+```bash
+paperclipai plugin list
+paperclipai plugin inspect acme.hello-plugin
+```
+
+`list` shows plugin key, status, version, and short error. `inspect` prints the same record with the full last error if there is one. Both accept `--json` if you want to script against them.
+
+## Reload semantics, honestly
+
+Paperclip watches the on-disk plugin package after a local install. The watcher targets the runtime entrypoints declared in the package's `paperclipPlugin` field (`dist/manifest.js`, `dist/worker.js`, `dist/ui/`).
+
+What that means in practice:
+
+- **Worker code:** save a `.ts` file → esbuild rewrites `dist/worker.js` → Paperclip debounces ~500ms and restarts the plugin worker. The next worker call uses the new code. There is no in-process hot module replacement for worker code; it is a worker restart.
+- **Manifest:** save `src/manifest.ts` → `dist/manifest.js` rewrites → the worker restarts and the host re-reads the manifest.
+- **Plugin UI:** save a `.tsx` file → esbuild rewrites `dist/ui/` → Paperclip reloads the UI bundle on its next mount. To get HMR during UI iteration, run `pnpm dev:ui` and point at the dev server with `devUiUrl` in your manifest while developing.
+- **Without `pnpm dev`:** the watcher only fires on `dist/*` changes. If you stop the watch build, source edits do not reach Paperclip. Restart `pnpm dev` (or run `pnpm build` once) before expecting changes.
+- **`node_modules`, `.git`, `.paperclip-sdk`, and other dotfolders are ignored.** Adding a dependency requires the new code to actually be imported and rebuilt before the worker sees it.
+
+The server never compiles plugin source for you. The package's own build scripts own that step.
+
+## Local path plugins vs npm packages
+
+Both go through the same install endpoint, but they mean different things:
+
+- **Local path plugins are trusted local code.** Paperclip executes worker code from disk under the same trust boundary as the rest of the running instance. This is meant for developing or operating a plugin against a checkout you control. There is no signature check, no sandboxing of worker code, and no provenance metadata beyond the path. Do not install local-path plugins you did not write.
+- **npm packages are the deployable artifact.** `paperclipai plugin install @acme/plugin-foo` (optionally `--version 1.2.3`) installs from your configured npm registry, version-pins, and produces an install record that other operators can reproduce. Ship plugins this way.
+
+When you are done iterating locally, publish the package and reinstall the npm-package form so the install reflects what you will ship.
+
+## Common things to do next
+
+- **Restart cleanly:** `paperclipai plugin disable <key>` pauses the plugin without removing it. `paperclipai plugin enable <key>` brings it back. `paperclipai plugin uninstall <key>` removes the install record; add `--force` to also purge plugin state and settings.
+- **Browse examples:** `paperclipai plugin examples` lists the bundled example plugins that ship with the repo, each with a ready-to-run `paperclipai plugin install <path>` line.
+- **Go deeper:** [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md) covers worker capabilities, managed agents/projects/routines, plugin database namespaces, scoped API routes, and the shared UI components in `@paperclipai/plugin-sdk/ui`. [`PLUGIN_SPEC.md`](./PLUGIN_SPEC.md) is the longer-form specification, including future ideas that are not yet implemented.
+
+## Troubleshooting
+
+- **`Plugin install returned no plugin record` or `error` status.** Run `paperclipai plugin inspect <key>` for the last error. The most common causes are (1) the plugin has not built yet — run `pnpm dev` or `pnpm build` first, (2) the `paperclipPlugin` entries in `package.json` point at files that do not exist on disk, or (3) the manifest failed validation. The Paperclip server log has the full validation error.
+- **Edits do not seem to reload.** Confirm `pnpm dev` is still running and writing to `dist/`. If you renamed entry files, update the `paperclipPlugin.manifest` / `paperclipPlugin.worker` / `paperclipPlugin.ui` fields in `package.json` so the watcher targets them.
+- **Worker restarts but UI is stale.** Hard-reload the page. If you want HMR, run `pnpm dev:ui` and set `devUiUrl` in your manifest to `http://127.0.0.1:4177` during development.
+- **Path arguments fail on Windows.** Quote paths that contain spaces, and prefer absolute paths over `~`-prefixed paths in non-bash shells.
diff --git a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md b/doc/plugins/PLUGIN_AUTHORING_GUIDE.md
index fc43ae7b7f..eb20163b17 100644
--- a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md
+++ b/doc/plugins/PLUGIN_AUTHORING_GUIDE.md
@@ -4,6 +4,8 @@ This guide describes the current, implemented way to create a Paperclip plugin i
It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec includes future ideas; this guide only covers the alpha surface that exists now.
+> **New to plugins?** Start with the short [Local Plugin Development guide](./LOCAL_PLUGIN_DEVELOPMENT.md) — it walks the CLI happy path (`plugin init` → `pnpm dev` → `plugin install <path>`) end to end. Come back here for the full manifest surface, worker capabilities, and UI components.
+
## Current reality
- Treat plugin workers and plugin UI as trusted code.
@@ -20,23 +22,13 @@ It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec i
## Scaffold a plugin
-Use the scaffold package:
-
-```bash
-pnpm --filter @paperclipai/create-paperclip-plugin build
-node packages/plugins/create-paperclip-plugin/dist/index.js @yourscope/plugin-name --output ./packages/plugins/examples
-```
-
-For a plugin that lives outside the Paperclip repo:
+Use the CLI scaffold command:
```bash
-pnpm --filter @paperclipai/create-paperclip-plugin build
-node packages/plugins/create-paperclip-plugin/dist/index.js @yourscope/plugin-name \
- --output /absolute/path/to/plugin-repos \
- --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
+paperclipai plugin init @yourscope/plugin-name --output /absolute/path/to/plugin-repos
```
-That creates a package with:
+That creates `<output>/plugin-name/` with:
- `src/manifest.ts`
- `src/worker.ts`
@@ -47,11 +39,13 @@ That creates a package with:
Inside this monorepo, the scaffold uses `workspace:*` for `@paperclipai/plugin-sdk`.
-Outside this monorepo, the scaffold snapshots `@paperclipai/plugin-sdk` from the local Paperclip checkout into a `.paperclip-sdk/` tarball so you can build and test a plugin without publishing anything to npm first.
+Outside this monorepo, the scaffold snapshots `@paperclipai/plugin-sdk` from the local Paperclip checkout into a `.paperclip-sdk/` tarball so you can build and test a plugin without publishing anything to npm first. Pass `--sdk-path /absolute/path/to/paperclip/packages/plugins/sdk` if you have more than one Paperclip checkout.
+
+## Local development workflow
-## Recommended local workflow
+See the short [Local Plugin Development guide](./LOCAL_PLUGIN_DEVELOPMENT.md) for the full happy path (`pnpm dev` → `paperclipai plugin install <absolute-path>` → `paperclipai plugin list`) and reload semantics.
-From the generated plugin folder:
+Minimum verification from the generated plugin folder:
```bash
pnpm install
@@ -60,16 +54,6 @@ pnpm test
pnpm build
```
-For local development, install it into Paperclip from an absolute local path through the plugin manager or API. The server supports local filesystem installs and watches local-path plugins for file changes so worker restarts happen automatically after rebuilds.
-
-Example:
-
-```bash
-curl -X POST http://127.0.0.1:3100/api/plugins/install \
- -H "Content-Type: application/json" \
- -d '{"packageName":"/absolute/path/to/your-plugin","isLocalPath":true}'
-```
-
## Supported alpha surface
Worker:
diff --git a/packages/plugins/create-paperclip-plugin/src/index.ts b/packages/plugins/create-paperclip-plugin/src/index.ts
index 5fc17b053f..099cb57eb7 100644
--- a/packages/plugins/create-paperclip-plugin/src/index.ts
+++ b/packages/plugins/create-paperclip-plugin/src/index.ts
@@ -62,6 +62,11 @@ function toPosixPath(value: string): string {
return value.split(path.sep).join("/");
}
+export function shellQuote(value: string): string {
+ if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(value)) return value;
+ return `'${value.replace(/'/g, "'\"'\"'")}'`;
+}
+
function formatFileDependency(absPath: string): string {
return `file:${toPosixPath(path.resolve(absPath))}`;
}
@@ -312,7 +317,8 @@ const manifest: PaperclipPluginManifestV1 = {
capabilities: [
"environment.drivers.register",
"plugin.state.read",
- "plugin.state.write"
+ "plugin.state.write",
+ "ui.dashboardWidget.register"
],
entrypoints: {
worker: "./dist/worker.js",
@@ -467,6 +473,11 @@ const BASE_PARAMS = {
};
describe("environment plugin scaffold", () => {
+ it("declares capabilities for its manifest features", () => {
+ expect(manifest.capabilities).toContain("environment.drivers.register");
+ expect(manifest.capabilities).toContain("ui.dashboardWidget.register");
+ });
+
it("validates config", async () => {
const driver = createFakeEnvironmentDriver({ driverKey: BASE_PARAMS.driverKey });
const harness = createEnvironmentTestHarness({ manifest, environmentDriver: driver });
@@ -533,7 +544,8 @@ const manifest: PaperclipPluginManifestV1 = {
capabilities: [
"events.subscribe",
"plugin.state.read",
- "plugin.state.write"
+ "plugin.state.write",
+ "ui.dashboardWidget.register"
],
entrypoints: {
worker: "./dist/worker.js",
@@ -623,6 +635,11 @@ import manifest from "../src/manifest.js";
import plugin from "../src/worker.js";
describe("plugin scaffold", () => {
+ it("declares capabilities for its manifest features", () => {
+ expect(manifest.capabilities).toContain("events.subscribe");
+ expect(manifest.capabilities).toContain("ui.dashboardWidget.register");
+ });
+
it("registers data + actions and handles events", async () => {
const harness = createTestHarness({ manifest, capabilities: [...manifest.capabilities, "events.emit"] });
await plugin.definition.setup(harness.ctx);
@@ -656,6 +673,11 @@ pnpm dev:ui # local dev server with hot-reload events
pnpm test
\`\`\`
+\`pnpm dev\` rebuilds the worker, manifest, and UI bundles into \`dist/\`.
+When this package is installed from a local path, Paperclip watches that rebuilt
+output and reloads the plugin worker. Local installs run trusted code from this
+folder on your machine.
+
${sdkDependency.startsWith("file:")
? `This scaffold snapshots \`@paperclipai/plugin-sdk\` and \`@paperclipai/shared\` from a local Paperclip checkout at:\n\n\`${toPosixPath(localSdkPath)}\`\n\nThe packed tarballs live in \`.paperclip-sdk/\` for local development. Before publishing this plugin, switch those dependencies to published package versions once they are available on npm.\n\n`
: ""}
@@ -663,9 +685,7 @@ ${sdkDependency.startsWith("file:")
## Install Into Paperclip
\`\`\`bash
-curl -X POST http://127.0.0.1:3100/api/plugins/install \\
- -H "Content-Type: application/json" \\
- -d '{"packageName":"${toPosixPath(outputDir)}","isLocalPath":true}'
+paperclipai plugin install ${shellQuote(toPosixPath(outputDir))}
\`\`\`
## Build Options
diff --git a/packages/plugins/examples/plugin-authoring-smoke-example/src/manifest.ts b/packages/plugins/examples/plugin-authoring-smoke-example/src/manifest.ts
index eb1c1efe1e..725c4dbf65 100644
--- a/packages/plugins/examples/plugin-authoring-smoke-example/src/manifest.ts
+++ b/packages/plugins/examples/plugin-authoring-smoke-example/src/manifest.ts
@@ -11,7 +11,8 @@ const manifest: PaperclipPluginManifestV1 = {
capabilities: [
"events.subscribe",
"plugin.state.read",
- "plugin.state.write"
+ "plugin.state.write",
+ "ui.dashboardWidget.register"
],
entrypoints: {
worker: "./dist/worker.js",
diff --git a/packages/plugins/examples/plugin-authoring-smoke-example/tests/plugin.spec.ts b/packages/plugins/examples/plugin-authoring-smoke-example/tests/plugin.spec.ts
index 8dddda8870..9f0451b04e 100644
--- a/packages/plugins/examples/plugin-authoring-smoke-example/tests/plugin.spec.ts
+++ b/packages/plugins/examples/plugin-authoring-smoke-example/tests/plugin.spec.ts
@@ -4,6 +4,11 @@ import manifest from "../src/manifest.js";
import plugin from "../src/worker.js";
describe("plugin scaffold", () => {
+ it("declares capabilities for its manifest features", () => {
+ expect(manifest.capabilities).toContain("events.subscribe");
+ expect(manifest.capabilities).toContain("ui.dashboardWidget.register");
+ });
+
it("registers data + actions and handles events", async () => {
const harness = createTestHarness({ manifest, capabilities: [...manifest.capabilities, "events.emit"] });
await plugin.definition.setup(harness.ctx);
diff --git a/packages/plugins/sdk/src/worker-rpc-host.ts b/packages/plugins/sdk/src/worker-rpc-host.ts
index 81104fea8f..643f9b0df4 100644
--- a/packages/plugins/sdk/src/worker-rpc-host.ts
+++ b/packages/plugins/sdk/src/worker-rpc-host.ts
@@ -34,6 +34,7 @@
* @see PLUGIN_SPEC.md §14 — SDK Surface
*/
+import fs from "node:fs";
import path from "node:path";
import { createInterface, type Interface as ReadlineInterface } from "node:readline";
import { fileURLToPath } from "node:url";
@@ -175,6 +176,21 @@ interface EventRegistration {
/** Default timeout for worker→host RPC calls. */
const DEFAULT_RPC_TIMEOUT_MS = 30_000;
+function realpathOrResolvedPath(filePath: string): string {
+ const resolvedPath = path.resolve(filePath);
+ try {
+ return fs.realpathSync.native(resolvedPath);
+ } catch {
+ return resolvedPath;
+ }
+}
+
+export function isWorkerEntrypoint(entry: string, moduleUrl: string): boolean {
+ const thisFile = realpathOrResolvedPath(fileURLToPath(moduleUrl));
+ const entryPath = realpathOrResolvedPath(entry);
+ return thisFile === entryPath;
+}
+
// ---------------------------------------------------------------------------
// startWorkerRpcHost
// ---------------------------------------------------------------------------
@@ -223,9 +239,7 @@ export function runWorker(
}
const entry = process.argv[1];
if (typeof entry !== "string") return;
- const thisFile = path.resolve(fileURLToPath(moduleUrl));
- const entryPath = path.resolve(entry);
- if (thisFile === entryPath) {
+ if (isWorkerEntrypoint(entry, moduleUrl)) {
startWorkerRpcHost({ plugin });
}
}
diff --git a/packages/plugins/sdk/tests/worker-rpc-host.test.ts b/packages/plugins/sdk/tests/worker-rpc-host.test.ts
new file mode 100644
index 0000000000..f8e0a38e5d
--- /dev/null
+++ b/packages/plugins/sdk/tests/worker-rpc-host.test.ts
@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { isWorkerEntrypoint } from "../src/worker-rpc-host.js";
+
+describe("isWorkerEntrypoint", () => {
+ const tempRoots: string[] = [];
+
+ afterEach(() => {
+ for (const tempRoot of tempRoots.splice(0)) {
+ fs.rmSync(tempRoot, { recursive: true, force: true });
+ }
+ });
+
+ function createTempRoot(): string {
+ const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-sdk-worker-"));
+ tempRoots.push(tempRoot);
+ return tempRoot;
+ }
+
+ it("matches an entrypoint reached through a symlinked directory", () => {
+ const tempRoot = createTempRoot();
+ const realDir = path.join(tempRoot, "real");
+ const linkDir = path.join(tempRoot, "link");
+ fs.mkdirSync(realDir);
+ fs.symlinkSync(realDir, linkDir, "dir");
+
+ const workerPath = path.join(realDir, "worker.js");
+ fs.writeFileSync(workerPath, "");
+
+ expect(
+ isWorkerEntrypoint(
+ path.join(linkDir, "worker.js"),
+ pathToFileURL(workerPath).toString(),
+ ),
+ ).toBe(true);
+ });
+
+ it("does not match a different entrypoint", () => {
+ const tempRoot = createTempRoot();
+ const workerPath = path.join(tempRoot, "worker.js");
+ const otherPath = path.join(tempRoot, "other.js");
+ fs.writeFileSync(workerPath, "");
+ fs.writeFileSync(otherPath, "");
+
+ expect(
+ isWorkerEntrypoint(
+ otherPath,
+ pathToFileURL(workerPath).toString(),
+ ),
+ ).toBe(false);
+ });
+});
diff --git a/packages/plugins/sdk/vitest.config.ts b/packages/plugins/sdk/vitest.config.ts
new file mode 100644
index 0000000000..faa6d98e10
--- /dev/null
+++ b/packages/plugins/sdk/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+ test: {
+ environment: "node",
+ include: ["tests/**/*.test.ts"],
+ },
+});
diff --git a/scripts/run-vitest-stable.mjs b/scripts/run-vitest-stable.mjs
index 4ded979458..c85c48aa9e 100644
--- a/scripts/run-vitest-stable.mjs
+++ b/scripts/run-vitest-stable.mjs
@@ -14,6 +14,7 @@ const nonServerProjects = [
"@paperclipai/adapter-acpx-local",
"@paperclipai/adapter-codex-local",
"@paperclipai/adapter-opencode-local",
+ "@paperclipai/plugin-sdk",
"@paperclipai/ui",
"paperclipai",
];
diff --git a/server/src/__tests__/plugin-dev-watcher.test.ts b/server/src/__tests__/plugin-dev-watcher.test.ts
index 75df310553..c6ffa74257 100644
--- a/server/src/__tests__/plugin-dev-watcher.test.ts
+++ b/server/src/__tests__/plugin-dev-watcher.test.ts
@@ -1,12 +1,28 @@
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { EventEmitter } from "node:events";
import os from "node:os";
import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { resolvePluginWatchTargets } from "../services/plugin-dev-watcher.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const chokidarMock = vi.hoisted(() => ({
+ watch: vi.fn(),
+}));
+
+vi.mock("chokidar", () => ({
+ default: chokidarMock,
+}));
+
+import { createPluginDevWatcher, resolvePluginWatchTargets } from "../services/plugin-dev-watcher.js";
const tempDirs: string[] = [];
+beforeEach(() => {
+ vi.useRealTimers();
+ chokidarMock.watch.mockReset();
+});
+
afterEach(() => {
+ vi.useRealTimers();
while (tempDirs.length > 0) {
const dir = tempDirs.pop();
if (dir) rmSync(dir, { recursive: true, force: true });
@@ -19,25 +35,49 @@ function makeTempPluginDir(): string {
return dir;
}
+function writePluginPackage(pluginDir: string): void {
+ mkdirSync(path.join(pluginDir, "dist", "ui"), { recursive: true });
+ writeFileSync(
+ path.join(pluginDir, "package.json"),
+ JSON.stringify({
+ name: "@acme/example",
+ paperclipPlugin: {
+ manifest: "./dist/manifest.js",
+ worker: "./dist/worker.js",
+ ui: "./dist/ui",
+ },
+ }),
+ );
+ writeFileSync(path.join(pluginDir, "dist", "manifest.js"), "export default {};\n");
+ writeFileSync(path.join(pluginDir, "dist", "worker.js"), "export default {};\n");
+ writeFileSync(path.join(pluginDir, "dist", "ui", "index.js"), "export default {};\n");
+ writeFileSync(path.join(pluginDir, "dist", "ui", "index.css"), "body {}\n");
+}
+
+function createLifecycle() {
+ const emitter = new EventEmitter();
+ return Object.assign(emitter, {
+ restartWorker: vi.fn().mockResolvedValue(undefined),
+ });
+}
+
+function installMockFsWatcher() {
+ const handlers: Record<string, (...args: unknown[]) => void> = {};
+ const fakeWatcher = {
+ close: vi.fn(),
+ on: vi.fn((event: string, listener: (...args: unknown[]) => void) => {
+ handlers[event] = listener;
+ return fakeWatcher;
+ }),
+ };
+ chokidarMock.watch.mockReturnValue(fakeWatcher);
+ return { fakeWatcher, handlers };
+}
+
describe("resolvePluginWatchTargets", () => {
it("watches package metadata plus concrete declared runtime files", () => {
const pluginDir = makeTempPluginDir();
- mkdirSync(path.join(pluginDir, "dist", "ui"), { recursive: true });
- writeFileSync(
- path.join(pluginDir, "package.json"),
- JSON.stringify({
- name: "@acme/example",
- paperclipPlugin: {
- manifest: "./dist/manifest.js",
- worker: "./dist/worker.js",
- ui: "./dist/ui",
- },
- }),
- );
- writeFileSync(path.join(pluginDir, "dist", "manifest.js"), "export default {};\n");
- writeFileSync(path.join(pluginDir, "dist", "worker.js"), "export default {};\n");
- writeFileSync(path.join(pluginDir, "dist", "ui", "index.js"), "export default {};\n");
- writeFileSync(path.join(pluginDir, "dist", "ui", "index.css"), "body {}\n");
+ writePluginPackage(pluginDir);
const targets = resolvePluginWatchTargets(pluginDir);
@@ -66,3 +106,43 @@ describe("resolvePluginWatchTargets", () => {
]);
});
});
+
+describe("createPluginDevWatcher", () => {
+ it("starts watching local plugins announced by lifecycle events", async () => {
+ const pluginDir = makeTempPluginDir();
+ writePluginPackage(pluginDir);
+ installMockFsWatcher();
+ const lifecycle = createLifecycle();
+
+ const devWatcher = createPluginDevWatcher(
+ lifecycle as never,
+ async (pluginId) => (pluginId === "plugin-1" ? pluginDir : null),
+ );
+
+ lifecycle.emit("plugin.loaded", { pluginId: "plugin-1", pluginKey: "example" });
+
+ await vi.waitFor(() => expect(chokidarMock.watch).toHaveBeenCalledTimes(1));
+ const [watchedPaths] = chokidarMock.watch.mock.calls[0] ?? [];
+ expect(watchedPaths).toContain(path.join(pluginDir, "dist", "worker.js"));
+
+ devWatcher.close();
+ });
+
+ it("debounces watched file changes and restarts the plugin worker", async () => {
+ vi.useFakeTimers();
+ const pluginDir = makeTempPluginDir();
+ writePluginPackage(pluginDir);
+ const { handlers } = installMockFsWatcher();
+ const lifecycle = createLifecycle();
+
+ const devWatcher = createPluginDevWatcher(lifecycle as never);
+ devWatcher.watch("plugin-1", pluginDir);
+
+ handlers.all?.("change", path.join(pluginDir, "dist", "worker.js"));
+ await vi.advanceTimersByTimeAsync(500);
+
+ expect(lifecycle.restartWorker).toHaveBeenCalledWith("plugin-1");
+
+ devWatcher.close();
+ });
+});
diff --git a/server/src/__tests__/plugin-routes-authz.test.ts b/server/src/__tests__/plugin-routes-authz.test.ts
index 52e678b46d..963d3cd1f1 100644
--- a/server/src/__tests__/plugin-routes-authz.test.ts
+++ b/server/src/__tests__/plugin-routes-authz.test.ts
@@ -224,6 +224,46 @@ describe.sequential("plugin install and upgrade authz", () => {
expect(mockLifecycle.disable).not.toHaveBeenCalled();
}, 20_000);
+ it("resolves plugin keys without probing the UUID id column for core plugin actions", async () => {
+ const pluginKey = "paperclipqa.hello-plugin";
+ const plugin = {
+ id: pluginId,
+ pluginKey,
+ version: "1.0.0",
+ status: "ready",
+ };
+ mockRegistry.getById.mockImplementation(() => {
+ throw new Error("getById should not be called for plugin keys");
+ });
+ mockRegistry.getByKey.mockResolvedValue(plugin);
+ mockLifecycle.unload.mockResolvedValue(plugin);
+ mockLifecycle.enable.mockResolvedValue(plugin);
+ mockLifecycle.disable.mockResolvedValue(plugin);
+
+ const { app } = await createApp({
+ type: "board",
+ userId: "admin-1",
+ source: "session",
+ isInstanceAdmin: true,
+ companyIds: [companyA],
+ });
+
+ const inspectRes = await request(app).get(`/api/plugins/${pluginKey}`);
+ const disableRes = await request(app).post(`/api/plugins/${pluginKey}/disable`).send({});
+ const enableRes = await request(app).post(`/api/plugins/${pluginKey}/enable`).send({});
+ const uninstallRes = await request(app).delete(`/api/plugins/${pluginKey}?purge=true`);
+
+ expect(inspectRes.status).toBe(200);
+ expect(disableRes.status).toBe(200);
+ expect(enableRes.status).toBe(200);
+ expect(uninstallRes.status).toBe(200);
+ expect(mockRegistry.getById).not.toHaveBeenCalled();
+ expect(mockRegistry.getByKey).toHaveBeenCalledWith(pluginKey);
+ expect(mockLifecycle.disable).toHaveBeenCalledWith(pluginId, undefined);
+ expect(mockLifecycle.enable).toHaveBeenCalledWith(pluginId);
+ expect(mockLifecycle.unload).toHaveBeenCalledWith(pluginId, true);
+ }, 20_000);
+
it("rejects plugin config saves that contain secret refs even for instance admins", async () => {
readyPlugin();
diff --git a/server/src/app.ts b/server/src/app.ts
index d94475afea..d037718420 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -420,12 +420,10 @@ export async function createApp(
void toolDispatcher.initialize().catch((err) => {
logger.error({ err }, "Failed to initialize plugin tool dispatcher");
});
- const devWatcher = opts.uiMode === "vite-dev"
- ? createPluginDevWatcher(
- lifecycle,
- async (pluginId) => (await pluginRegistry.getById(pluginId))?.packagePath ?? null,
- )
- : null;
+ const devWatcher = createPluginDevWatcher(
+ lifecycle,
+ async (pluginId) => (await pluginRegistry.getById(pluginId))?.packagePath ?? null,
+ );
void loader.loadAll().then((result) => {
if (!result) return;
for (const loaded of result.results) {
diff --git a/server/src/routes/plugins.ts b/server/src/routes/plugins.ts
index 75a206b154..443685187c 100644
--- a/server/src/routes/plugins.ts
+++ b/server/src/routes/plugins.ts
@@ -199,9 +199,9 @@ function listBundledPluginExamples(): AvailablePluginExample[] {
*
* Lookup order:
* - UUID-like IDs: getById first, then getByKey.
- * - Scoped package keys (e.g. "@scope/name"): getByKey only, never getById.
- * - Other non-UUID IDs: try getById first (test/memory registries may allow this),
- * then fallback to getByKey. Any UUID parse error from getById is ignored.
+ * - All non-UUID values: getByKey only, never getById. The persisted plugin
+ * ID column is a PostgreSQL UUID, so probing it with keys such as
+ * "acme.plugin" raises a database cast error before a key lookup can happen.
*
* @param registry - The plugin registry service instance
* @param pluginId - Either a database UUID or plugin key (manifest id)
@@ -212,27 +212,13 @@ async function resolvePlugin(
pluginId: string,
) {
const isUuid = UUID_REGEX.test(pluginId);
- const isScopedPackageKey = pluginId.startsWith("@") || pluginId.includes("/");
- // Scoped package IDs are valid plugin keys but invalid UUIDs.
- // Skip getById() entirely to avoid Postgres uuid parse errors.
- if (isScopedPackageKey && !isUuid) {
+ if (!isUuid) {
return registry.getByKey(pluginId);
}
- try {
- const byId = await registry.getById(pluginId);
- if (byId) return byId;
- } catch (error) {
- const maybeCode =
- typeof error === "object" && error !== null && "code" in error
- ? (error as { code?: unknown }).code
- : undefined;
- // Ignore invalid UUID cast errors and continue with key lookup.
- if (maybeCode !== "22P02") {
- throw error;
- }
- }
+ const byId = await registry.getById(pluginId);
+ if (byId) return byId;
return registry.getByKey(pluginId);
}
diff --git a/server/src/services/plugin-dev-watcher.ts b/server/src/services/plugin-dev-watcher.ts
index 76b258c421..ceba5d4e18 100644
--- a/server/src/services/plugin-dev-watcher.ts
+++ b/server/src/services/plugin-dev-watcher.ts
@@ -164,6 +164,10 @@ export function createPluginDevWatcher(
const watchers = new Map<string, FSWatcher>();
const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
const fileExists = fsDeps?.existsSync ?? existsSync;
+ log.info(
+ { resolvesInstalledPlugins: Boolean(resolvePluginPackagePath) },
+ "plugin-dev-watcher: initialized",
+ );
function watchPlugin(pluginId: string, packagePath: string): void {
// Don't double-watch
@@ -293,11 +297,23 @@ export function createPluginDevWatcher(
}
async function watchLocalPluginById(pluginId: string): Promise<void> {
- if (!resolvePluginPackagePath) return;
+ if (!resolvePluginPackagePath) {
+ log.debug(
+ { pluginId },
+ "plugin-dev-watcher: no package path resolver configured, skipping lifecycle event",
+ );
+ return;
+ }
try {
const packagePath = await resolvePluginPackagePath(pluginId);
- if (!packagePath) return;
+ if (!packagePath) {
+ log.debug(
+ { pluginId },
+ "plugin-dev-watcher: plugin is not a local-path install, skipping watch",
+ );
+ return;
+ }
watchPlugin(pluginId, packagePath);
} catch (err) {
log.warn(
diff --git a/skills/paperclip-create-plugin/SKILL.md b/skills/paperclip-create-plugin/SKILL.md
index b288a08192..4dda697d64 100644
--- a/skills/paperclip-create-plugin/SKILL.md
+++ b/skills/paperclip-create-plugin/SKILL.md
@@ -1,23 +1,34 @@
---
name: paperclip-create-plugin
description: >
- Create new Paperclip plugins with the current alpha SDK/runtime. Use when
- scaffolding a plugin package, adding a new example plugin, or updating plugin
- authoring docs. Covers the supported worker/UI surface, route conventions,
- scaffold flow, and verification steps.
+ Create and develop external Paperclip plugins with the CLI-first workflow.
+ Use when scaffolding a new plugin, working on a local plugin against a running
+ Paperclip instance, or updating plugin authoring docs. Covers `paperclipai
+ plugin init`, the local install loop via `paperclipai plugin install <path>`,
+ worker/UI rebuild and reload semantics, and the required success checklist.
---
-# Create a Paperclip Plugin
+# Create and develop a Paperclip plugin
-Use this skill when the task is to create, scaffold, or document a Paperclip plugin.
+Use this skill when the task is to create, scaffold, or iterate on a Paperclip plugin against a local Paperclip instance.
-## 1. Ground rules
+## 1. Default: build the plugin OUTSIDE Paperclip core
-Read these first when needed:
+Plugins are their own packages. Unless the task **explicitly** asks for a bundled in-repo example, do not add plugin source under `packages/plugins/` in this repo.
+
+- Scaffold the plugin into a directory outside the Paperclip checkout (e.g. `~/dev/paperclip-plugins/<name>`).
+- Install it into the running Paperclip instance by local absolute path.
+- Edit code in the external package; let Paperclip pick up rebuilt output.
+
+Only edit Paperclip core itself when the user asks to surface a plugin as a bundled example (`server/src/routes/plugins.ts`, in-repo example lists, docs).
+
+## 2. Ground rules
+
+Reference docs when you need detail:
1. `doc/plugins/PLUGIN_AUTHORING_GUIDE.md`
2. `packages/plugins/sdk/README.md`
-3. `doc/plugins/PLUGIN_SPEC.md` only for future-looking context
+3. `doc/plugins/PLUGIN_SPEC.md` — future-looking context only
Current runtime assumptions:
@@ -28,38 +39,67 @@ Current runtime assumptions:
- no host-provided shared plugin UI component kit yet
- `ctx.assets` is not supported in the current runtime
-## 2. Preferred workflow
+## 3. CLI-first scaffold workflow
-Use the scaffold package instead of hand-writing the boilerplate:
+Use `paperclipai plugin init`. Do not invoke the scaffold package node entrypoint by hand unless the CLI command is unavailable in the environment.
```bash
-pnpm --filter @paperclipai/create-paperclip-plugin build
-node packages/plugins/create-paperclip-plugin/dist/index.js <npm-package-name> --output <target-dir>
+paperclipai plugin init @acme/my-plugin --output ~/dev/paperclip-plugins
```
-For a plugin that lives outside the Paperclip repo, pass `--sdk-path` and let the scaffold snapshot the local SDK/shared packages into `.paperclip-sdk/`:
+Useful flags (all optional):
+
+- `--output <dir>` — parent directory; the command creates `<dir>/<unscoped-name>/`. Defaults to the current directory.
+- `--template <default|connector|workspace|environment>` — starter template.
+- `--category <connector|workspace|automation|ui|environment>` — manifest category.
+- `--display-name <name>`, `--description <text>`, `--author <name>` — manifest metadata.
+- `--sdk-path <path>` — snapshot the local SDK from a Paperclip checkout into `.paperclip-sdk/` (useful when developing against an unreleased SDK).
+
+On success the command prints the exact next commands (`cd`, `pnpm install`, `pnpm dev`, `paperclipai plugin install <abs-path>`). Run them in order.
+
+If `paperclipai` is not on PATH in your environment, fall back to:
```bash
pnpm --filter @paperclipai/create-paperclip-plugin build
-node packages/plugins/create-paperclip-plugin/dist/index.js @acme/plugin-name \
- --output /absolute/path/to/plugin-repos \
+node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
+ --output /absolute/path \
--sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
```
-Recommended target inside this repo:
+## 4. Local install + rebuild loop
+
+In the scaffolded plugin folder:
+
+```bash
+pnpm install
+pnpm dev # esbuild --watch: rebuilds dist/manifest.js, dist/worker.js, dist/ui/
+paperclipai plugin install /absolute/path/to/my-plugin
+```
+
+Notes:
-- `packages/plugins/examples/` for example plugins
-- another `packages/plugins/<name>/` folder if it is becoming a real package
+- `paperclipai plugin install` auto-detects local paths (absolute, `./`, `../`, `~`, or an existing relative folder) and forwards `isLocalPath: true` to the server. Pass `--local` to force local mode if the heuristic is ambiguous.
+- Paths are resolved to absolute paths before being sent to the server.
+- The server watches built outputs (`dist/`) for local-path plugins and restarts the plugin worker on rebuild — you do not need to reinstall after every edit.
+- UI hot reload via the SDK dev server (`pnpm dev:ui`, port `4177`) is optional and template-dependent; only mention it if the template wires `devUiUrl` and you verified it works end to end.
+- `--version` only applies to npm package installs. Combining it with a local path is an error.
-## 3. After scaffolding
+After install, inspect with:
-Check and adjust:
+```bash
+paperclipai plugin list
+paperclipai plugin inspect <plugin-key>
+```
+
+## 5. After scaffolding, sanity-check the package
+
+Open and confirm:
-- `src/manifest.ts`
-- `src/worker.ts`
-- `src/ui/index.tsx`
-- `tests/plugin.spec.ts`
-- `package.json`
+- `src/manifest.ts` — declared capabilities and slots
+- `src/worker.ts` — worker entry
+- `src/ui/index.tsx` — UI entry (if applicable)
+- `tests/plugin.spec.ts` — placeholder test
+- `package.json` — `paperclipPlugin` block points at `dist/manifest.js`, `dist/worker.js`, `dist/ui/`
Make sure the plugin:
@@ -68,34 +108,47 @@ Make sure the plugin:
- does not import host UI component stubs
- keeps UI self-contained
- uses `routePath` only on `page` slots
-- is installed into Paperclip from an absolute local path during development
-## 4. If the plugin should appear in the app
+## 6. Verification (run before declaring success)
-For bundled example/discoverable behavior, update the relevant host wiring:
+From the plugin folder:
-- bundled example list in `server/src/routes/plugins.ts`
-- any docs that list in-repo examples
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+```
-Only do this if the user wants the plugin surfaced as a bundled example.
+If the plugin is already running under `pnpm dev`, you can keep the watcher up and run `pnpm typecheck` and `pnpm test` in a separate shell.
-## 5. Verification
+If you changed Paperclip SDK/host/plugin runtime code in addition to the plugin, also run the relevant Paperclip workspace checks.
-Always run:
+## 7. Success checklist (report this back)
-```bash
-pnpm --filter <plugin-package> typecheck
-pnpm --filter <plugin-package> test
-pnpm --filter <plugin-package> build
-```
+When you finish a local plugin task, report:
+
+- **Scaffold path** — absolute path of the created plugin folder.
+- **Commands run** — the exact `paperclipai plugin init`, `pnpm install`, `pnpm dev`, `paperclipai plugin install <path>` invocations (and any verification commands).
+- **Install status** — output of `paperclipai plugin list` / `plugin inspect` (plugin key, version, status). Note if `status` is anything other than `ready` and include `lastError`.
+- **Tests / build result** — `pnpm typecheck`, `pnpm test`, `pnpm build` pass/fail with the failing output if any.
+- **Reload limitations** — call out anything that did not hot-reload (e.g. manifest changes required a reinstall, UI dev server was not wired, etc.).
+
+If any item is missing, mark it as such — do not silently skip.
+
+## 8. When NOT to edit Paperclip core
+
+Do not add the plugin under `packages/plugins/` or update bundled-example wiring unless the user explicitly asks for a bundled example. Local-path installs are the supported development model; npm packages are the production deployment path.
+
+If the user does ask for a bundled example, also update:
-If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
+- `server/src/routes/plugins.ts` example list
+- any docs that enumerate in-repo example plugins
-## 6. Documentation expectations
+## 9. Documentation expectations
When authoring or updating plugin docs:
- distinguish current implementation from future spec ideas
- be explicit about the trusted-code model
- do not promise host UI components or asset APIs
-- prefer npm-package deployment guidance over repo-local workflows for production
+- prefer local-path development + npm-package deployment guidance over repo-local workflows
diff --git a/vitest.config.ts b/vitest.config.ts
index 42b8e87921..f27929e74f 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -14,6 +14,7 @@ export default defineConfig({
"packages/adapters/gemini-local",
"packages/adapters/opencode-local",
"packages/adapters/pi-local",
+ "packages/plugins/sdk",
"server",
"ui",
"cli",