aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify plugin authoring and external dev workflow

Browse Source
This commit is contained in:
Dotta
2026-03-14 10:40:21 -05:00
parent cb5d7e76fb
commit 30888759f2
36 changed files with 693 additions and 410 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
packages/plugins/create-paperclip-plugin/README.md
View File

@@ -22,11 +22,25 @@ Supported categories: `connector`, `workspace`, `automation`, `ui`
Generates:
- typed manifest + worker entrypoint
- example UI widget using `@paperclipai/plugin-sdk/ui`
- example UI widget using the supported `@paperclipai/plugin-sdk/ui` hooks
- test file using `@paperclipai/plugin-sdk/testing`
- `esbuild` and `rollup` config files using SDK bundler presets
- dev server script for hot-reload (`paperclip-plugin-dev-server`)
The scaffold intentionally uses plain React elements rather than host-provided UI kit components, because the current plugin runtime does not ship a stable shared component library yet.
Inside this repo, the generated package uses `@paperclipai/plugin-sdk` via `workspace:*`.
Outside this repo, the scaffold snapshots `@paperclipai/plugin-sdk` from your local Paperclip checkout into a `.paperclip-sdk/` tarball and points the generated package at that local file by default. You can override the SDK source explicitly:
```bash
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
--output /absolute/path/to/plugins \
--sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
```
That gives you an outside-repo local development path before the SDK is published to npm.
## Workflow after scaffolding
```bash

120
packages/plugins/create-paperclip-plugin/src/index.ts
View File

@@ -1,6 +1,8 @@
#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
const VALID_TEMPLATES = ["default", "connector", "workspace"] as const;
type PluginTemplate = (typeof VALID_TEMPLATES)[number];
@@ -14,6 +16,7 @@ export interface ScaffoldPluginOptions {
description?: string;
author?: string;
category?: "connector" | "workspace" | "automation" | "ui";
sdkPath?: string;
}
/** Validate npm-style plugin package names (scoped or unscoped). */
@@ -55,6 +58,58 @@ function quote(value: string): string {
return JSON.stringify(value);
}
function toPosixPath(value: string): string {
return value.split(path.sep).join("/");
}
function formatFileDependency(absPath: string): string {
return `file:${toPosixPath(path.resolve(absPath))}`;
}
function getLocalSdkPackagePath(): string {
return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "sdk");
}
function getRepoRootFromSdkPath(sdkPath: string): string {
return path.resolve(sdkPath, "..", "..", "..");
}
function getLocalSharedPackagePath(sdkPath: string): string {
return path.resolve(getRepoRootFromSdkPath(sdkPath), "packages", "shared");
}
function isInsideDir(targetPath: string, parentPath: string): boolean {
const relative = path.relative(parentPath, targetPath);
return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
}
function packLocalPackage(packagePath: string, outputDir: string): string {
const packageJsonPath = path.join(packagePath, "package.json");
if (!fs.existsSync(packageJsonPath)) {
throw new Error(`Package package.json not found at ${packageJsonPath}`);
}
const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) as {
name?: string;
version?: string;
};
const packageName = packageJson.name ?? path.basename(packagePath);
const packageVersion = packageJson.version ?? "0.0.0";
const tarballFileName = `${packageName.replace(/^@/, "").replace("/", "-")}-${packageVersion}.tgz`;
const sdkBundleDir = path.join(outputDir, ".paperclip-sdk");
fs.mkdirSync(sdkBundleDir, { recursive: true });
execFileSync("pnpm", ["build"], { cwd: packagePath, stdio: "pipe" });
execFileSync("pnpm", ["pack", "--pack-destination", sdkBundleDir], { cwd: packagePath, stdio: "pipe" });
const tarballPath = path.join(sdkBundleDir, tarballFileName);
if (!fs.existsSync(tarballPath)) {
throw new Error(`Packed tarball was not created at ${tarballPath}`);
}
return tarballPath;
}
/**
* Generate a complete Paperclip plugin starter project.
*
@@ -85,9 +140,18 @@ export function scaffoldPluginProject(options: ScaffoldPluginOptions): string {
const author = options.author ?? "Plugin Author";
const category = options.category ?? (template === "workspace" ? "workspace" : "connector");
const manifestId = packageToManifestId(options.pluginName);
const localSdkPath = path.resolve(options.sdkPath ?? getLocalSdkPackagePath());
const localSharedPath = getLocalSharedPackagePath(localSdkPath);
const repoRoot = getRepoRootFromSdkPath(localSdkPath);
const useWorkspaceSdk = isInsideDir(outputDir, repoRoot);
fs.mkdirSync(outputDir, { recursive: true });
const packedSharedTarball = useWorkspaceSdk ? null : packLocalPackage(localSharedPath, outputDir);
const sdkDependency = useWorkspaceSdk
? "workspace:*"
: `file:${toPosixPath(path.relative(outputDir, packLocalPackage(localSdkPath, outputDir)))}`;
const packageJson = {
name: options.pluginName,
version: "0.1.0",
@@ -99,7 +163,7 @@ export function scaffoldPluginProject(options: ScaffoldPluginOptions): string {
"build:rollup": "rollup -c",
dev: "node ./esbuild.config.mjs --watch",
"dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
test: "vitest run",
test: "vitest run --config ./vitest.config.ts",
typecheck: "tsc --noEmit"
},
paperclipPlugin: {
@@ -110,10 +174,22 @@ export function scaffoldPluginProject(options: ScaffoldPluginOptions): string {
keywords: ["paperclip", "plugin", category],
author,
license: "MIT",
dependencies: {
"@paperclipai/plugin-sdk": "^1.0.0"
},
...(packedSharedTarball
? {
pnpm: {
overrides: {
"@paperclipai/shared": `file:${toPosixPath(path.relative(outputDir, packedSharedTarball))}`,
},
},
}
: {}),
devDependencies: {
...(packedSharedTarball
? {
"@paperclipai/shared": `file:${toPosixPath(path.relative(outputDir, packedSharedTarball))}`,
}
: {}),
"@paperclipai/plugin-sdk": sdkDependency,
"@rollup/plugin-node-resolve": "^16.0.1",
"@rollup/plugin-typescript": "^12.1.2",
"@types/node": "^24.6.0",
@@ -144,7 +220,7 @@ export function scaffoldPluginProject(options: ScaffoldPluginOptions): string {
declarationMap: true,
sourceMap: true,
outDir: "dist",
rootDir: "src"
rootDir: "."
},
include: ["src", "tests"],
exclude: ["dist", "node_modules"]
@@ -207,6 +283,19 @@ export default [
`,
);
writeFile(
path.join(outputDir, "vitest.config.ts"),
`import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
include: ["tests/**/*.spec.ts"],
environment: "node",
},
});
`,
);
writeFile(
path.join(outputDir, "src", "manifest.ts"),
`import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
@@ -278,7 +367,7 @@ runWorker(plugin, import.meta.url);
writeFile(
path.join(outputDir, "src", "ui", "index.tsx"),
`import { MetricCard, StatusBadge, usePluginAction, usePluginData, type PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
`import { usePluginAction, usePluginData, type PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
type HealthData = {
status: "ok" | "degraded" | "error";
@@ -290,11 +379,13 @@ export function DashboardWidget(_props: PluginWidgetProps) {
const ping = usePluginAction("ping");
if (loading) return <div>Loading plugin health...</div>;
if (error) return <StatusBadge label={error.message} status="error" />;
if (error) return <div>Plugin error: {error.message}</div>;
return (
<div style={{ display: "grid", gap: "0.5rem" }}>
<MetricCard label="Health" value={data?.status ?? "unknown"} />
<strong>${displayName}</strong>
<div>Health: {data?.status ?? "unknown"}</div>
<div>Checked: {data?.checkedAt ?? "never"}</div>
<button onClick={() => void ping()}>Ping Worker</button>
</div>
);
@@ -342,10 +433,16 @@ pnpm dev:ui # local dev server with hot-reload events
pnpm test
\`\`\`
${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`
: ""}
## Install Into Paperclip
\`\`\`bash
pnpm paperclipai plugin install ./
curl -X POST http://127.0.0.1:3100/api/plugins/install \\
-H "Content-Type: application/json" \\
-d '{"packageName":"${toPosixPath(outputDir)}","isLocalPath":true}'
\`\`\`
## Build Options
@@ -355,7 +452,7 @@ pnpm paperclipai plugin install ./
`,
);
writeFile(path.join(outputDir, ".gitignore"), "dist\nnode_modules\n");
writeFile(path.join(outputDir, ".gitignore"), "dist\nnode_modules\n.paperclip-sdk\n");
return outputDir;
}
@@ -371,7 +468,7 @@ function runCli() {
const pluginName = process.argv[2];
if (!pluginName) {
// eslint-disable-next-line no-console
console.error("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>]");
console.error("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>] [--sdk-path <paperclip-sdk-path>]");
process.exit(1);
}
@@ -387,6 +484,7 @@ function runCli() {
description: parseArg("--description"),
author: parseArg("--author"),
category: parseArg("--category") as ScaffoldPluginOptions["category"] | undefined,
sdkPath: parseArg("--sdk-path"),
});
// eslint-disable-next-line no-console