Files
PaperClipAI/packages/plugins/create-paperclip-plugin/src/index.ts
T
DottaandClaude Opus 5.5 f4cb69205e Let plugin workers serve connector tools (plugin transport) (#22019)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Plugins can now add connector types to the Connectors catalog
(#22004), but only for transports the host already runs (remote MCP,
local stdio)
> - A plugin cannot yet serve a connector's tools itself, and legacy
plugin tools (top-level manifest `tools`) still reach every agent
without a connection or install
> - A plugin should be able to ship a full connector: settings,
credentials, tools, grants, policies and audit, like a built-in one
> - This pull request adds the `plugin` transport, the SDK API to serve
it, and moves legacy plugin tools under the same activation rules
without changing today's access
> - The benefit is that any connector can live in a plugin, and agents
get plugin tools only when an operator enables them

## Linked Issues or Issue Description

Refs #22004

**Subsystem affected**
Plugins (SDK, worker protocol, manifest), Connectors (tool access,
catalog discovery), tool gateway, database.

**Problem or motivation**
A plugin connector can only describe an existing transport. There is no
way for a plugin worker to serve a connector's tools with per-connection
settings and credentials. Legacy plugin tools are visible to every agent
as soon as the plugin is enabled, which is the opposite of the connector
activation rules.

**Proposed solution**
Add a `plugin` transport. The gateway keeps every decision (grant,
policy, approval, rate limit, audit) and calls the plugin worker with
the connection, its settings and a per-call credential. Legacy top-level
tools become one implicit connector per plugin. Existing installations
keep exactly their current access through a one-time migration.

**Alternatives considered**
Move legacy tools to connection tool names (`app.<connection>:<tool>`).
Rejected: names change, so existing tool policies and agent instructions
that name `plugin:tool` would stop matching (a possible widening or
loss). Legacy tools keep their names and handlers; only their visibility
is now gated by an install of the implicit connector.

## What Changed

- `packages/db`: migration `0491` widens
`tool_connections_transport_check` with `plugin` (`NOT VALID`, annotated
`online_compatible`), and adds `plugin_connector_legacy_access`, seeded
with one row per installed legacy-tools plugin and company.
- `packages/shared`: method schema gains `settingsSchema` and `tools`
(`{ kind: "static", list: [{ name, displayName?, description?, risk,
parametersSchema }] } | { kind: "dynamic" }`), only for `transport:
"plugin"`; tool names must match `[a-z0-9_]`; plugin-served methods use
`none` or `api_key`. The connect API accepts `settings`.
- `packages/plugins/sdk`: `ToolRunContext.connection` (`id`, `appSlug`,
`methodKey`, `grantId`, `settings`, `credential?`);
`ctx.connectors.register(appSlug, toolName, fn)` and
`ctx.connectors.listTools(appSlug, fn)`; new `listConnectorTools` RPC;
`executeTool` routes connector calls by `appSlug`. A worker refuses to
start when a declared static tool (or dynamic lister) has no handler.
The test harness gains `executeConnectorTool` and `listConnectorTools`.
- `server/src/services/plugin-connector-runtime.ts`: routes one call to
the plugin's worker; a stopped worker is a
`PluginWorkerUnavailableError`.
- Connect flow (`tool-access.ts`): a `plugin` method creates a
`paperclip_plugin` application and a `plugin` connection with `config =
{ sourceTemplateKey, connectionMethodKey, settings }`, validated against
`settingsSchema`. Credentials, grants, credential policy, installs and
profiles use the existing code.
- Catalog: static tools come from the definition, dynamic tools from
`listConnectorTools`, with the existing version hashing and retirement.
Tool risk comes from the declaration.
- Gateway: plugin connections join connected-tool discovery and both
execution paths (direct and approved actions). For each call the gateway
resolves the grant and, for `api_key`, the credential for that call
only. The run context comes only from the session. A stopped worker
returns `503 plugin_connector_unavailable` with `retryable: true`. The
token broker refuses to export plugin connector credentials.
- Legacy tools: a plugin with top-level `tools` and no `apps` gets an
implicit connector (slug `default`, named after the plugin, no
authentication). Its tools keep their names, handlers and today's access
decision, and an agent sees them only when a connection of that
connector is installed for it or for the company. The connector's saved
action rules (Off, Ask first) can only restrict them.
`completeLegacyPluginToolAccess` turns each migration row into such a
connection with a company install, at boot and when a disabled plugin is
enabled again; it is single-flight across servers, resumes a draft left
by an interrupted attempt, and never overrides an operator's later
changes.
- Catalog: tools a dynamic connector stops offering are retired from
discovery; `listConnectorTools` carries the connection's `companyId`,
and uses the acting person's grant for personal connections.
- Board: the setup flow renders `settingsSchema` with the shared JSON
Schema form, sends `settings`, and restores saved settings on resume and
reconnect.
- `create-paperclip-plugin --template connector` now scaffolds a plugin
connector (`apps` + `ctx.connectors.register` + a harness test). SDK
README and `PLUGIN_SPEC.md` describe connectors; top-level `tools` stay
documented as legacy.
- `inferToolRisk` moves to `tool-risk-inference.ts` so the catalog can
reuse it.

Design notes where the spec left room:
- OAuth for `plugin`-transport methods is not supported in this PR
(`none` and `api_key` only); OAuth plugin connectors can use
`mcp_remote` today. Noted as follow-up.
- Board "Test" calls on a plugin connection pass an empty
`agentId`/`runId`, because there is no agent run.
- Companies created after the upgrade get no automatic legacy
connection; they follow the normal activation rules.

## Verification

- `server`: `npx vitest run
src/__tests__/plugin-connectors-plugin-transport.test.ts` (new):
- rules 1-3: a ready plugin and configured accounts give no tools; an
install for agent A gives only A the tools; agent B is denied on
invocation;
- the worker receives `runContext.connection` with the right id, method,
grant, settings and the call's credential; spoofed arguments do not
change it; each account calls with its own key; results do not contain
the key;
- invalid settings are rejected (422); a stopped worker is `503
plugin_connector_unavailable` (retryable); a disabled plugin hides the
tools;
- dynamic tools are listed through the worker and a tool it stops
offering is retired;
- rule 5: a new installation of a legacy-tools plugin gives no tools; an
installation recorded by the migration keeps the same tool names for
every agent, through one company-wide connection (two concurrent
carry-overs make one; an interrupted draft is finished; a retry keeps an
operator's restriction), and is not also exposed as connection tools;
Ask first and Off on the implicit connector restrict the legacy tools;
  - the token broker refuses to export a plugin connection's credential.
- Existing gateway plugin-tool tests (`tool-gateway`,
`tool-gateway-service`, `prompt-injection-gateway`) now set up the
legacy grant an existing installation has, and pass unchanged otherwise.
- Regression: `plugin-connectors-circleback-parity`, `tool-gateway`,
`tool-gateway-service`, `prompt-injection-gateway`,
`tool-access-service` (846 passed), plus `connector-tool-policy`,
`plugin-lifecycle-restart`, `remote-mcp-connectors`,
`ai-connection-router` in an earlier run.
- UI: `AppsConnect.test.tsx` covers sending plugin settings from the
settings schema.
- SDK: `tests/worker-rpc-host.test.ts` (start refusal without handlers,
connector routing, tool listing). Scaffold: `entrypoints.test.ts`.
- `packages/db`: `pnpm typecheck` including `check:migrations`; server
layered typecheck (sources and tests); `tsc --noEmit` for shared, SDK,
scaffold and UI.

## Risks

- Behavior change for new installations: legacy plugin tools no longer
reach agents until an operator connects the plugin's connector.
Installations that exist at upgrade time keep their tools through the
migration rows.
- The migration widens a check constraint (`NOT VALID`) and copies
plugin × company rows into a new table. Both are fast; the previous
release never writes `plugin`.
- Calls depend on the plugin worker; when it is down the agent gets a
retryable error.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file editing, test execution).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 18:09:42 +00:00

766 lines
24 KiB
TypeScript

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", "environment"] as const;
type PluginTemplate = (typeof VALID_TEMPLATES)[number];
const VALID_CATEGORIES = new Set(["connector", "workspace", "automation", "ui", "environment"] as const);
export interface ScaffoldPluginOptions {
pluginName: string;
outputDir: string;
template?: PluginTemplate;
displayName?: string;
description?: string;
author?: string;
category?: "connector" | "workspace" | "automation" | "ui" | "environment";
sdkPath?: string;
}
/** Validate npm-style plugin package names (scoped or unscoped). */
export function isValidPluginName(name: string): boolean {
const scopedPattern = /^@[a-z0-9_-]+\/[a-z0-9._-]+$/;
const unscopedPattern = /^[a-z0-9._-]+$/;
return scopedPattern.test(name) || unscopedPattern.test(name);
}
/** Convert `@scope/name` to an output directory basename (`name`). */
function packageToDirName(pluginName: string): string {
return pluginName.replace(/^@[^/]+\//, "");
}
/** Convert an npm package name into a manifest-safe plugin id. */
function packageToManifestId(pluginName: string): string {
if (!pluginName.startsWith("@")) {
return pluginName;
}
return pluginName.slice(1).replace("/", ".");
}
/** Build a human-readable display name from package name tokens. */
function makeDisplayName(pluginName: string): string {
const raw = packageToDirName(pluginName).replace(/[._-]+/g, " ").trim();
return raw
.split(/\s+/)
.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
.join(" ");
}
function writeFile(target: string, content: string) {
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, content);
}
function quote(value: string): string {
return JSON.stringify(value);
}
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))}`;
}
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.
*
* Output includes manifest/worker/UI entries, SDK harness tests, bundler presets,
* and a local dev server script for hot-reload workflow.
*/
export function scaffoldPluginProject(options: ScaffoldPluginOptions): string {
const template = options.template ?? "default";
if (!VALID_TEMPLATES.includes(template)) {
throw new Error(`Invalid template '${template}'. Expected one of: ${VALID_TEMPLATES.join(", ")}`);
}
if (!isValidPluginName(options.pluginName)) {
throw new Error("Invalid plugin name. Must be lowercase and may include scope, dots, underscores, or hyphens.");
}
if (options.category && !VALID_CATEGORIES.has(options.category)) {
throw new Error(`Invalid category '${options.category}'. Expected one of: ${[...VALID_CATEGORIES].join(", ")}`);
}
const outputDir = path.resolve(options.outputDir);
if (fs.existsSync(outputDir)) {
throw new Error(`Directory already exists: ${outputDir}`);
}
const displayName = options.displayName ?? makeDisplayName(options.pluginName);
const description = options.description ?? "A Paperclip plugin";
const author = options.author ?? "Plugin Author";
const category = options.category ?? (template === "workspace" ? "workspace" : template === "environment" ? "environment" : "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",
type: "module",
private: true,
description,
scripts: {
build: "node ./esbuild.config.mjs",
"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 --config ./vitest.config.ts",
typecheck: "tsc --noEmit"
},
paperclipPlugin: {
manifest: "./dist/manifest.js",
worker: "./dist/worker.js",
ui: "./dist/ui/"
},
keywords: ["paperclip", "plugin", category],
author,
license: "MIT",
...(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.0.0",
"@types/react": "^19.0.8",
esbuild: "^0.27.3",
rollup: "^4.38.0",
tslib: "^2.8.1",
typescript: "^5.7.3",
vitest: "^3.0.5"
},
peerDependencies: {
react: ">=18"
}
};
writeFile(path.join(outputDir, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`);
const tsconfig = {
compilerOptions: {
target: "ES2022",
module: "NodeNext",
moduleResolution: "NodeNext",
lib: ["ES2022", "DOM"],
jsx: "react-jsx",
strict: true,
skipLibCheck: true,
declaration: true,
declarationMap: true,
sourceMap: true,
outDir: "dist",
rootDir: "."
},
include: ["src", "tests"],
exclude: ["dist", "node_modules"]
};
writeFile(path.join(outputDir, "tsconfig.json"), `${JSON.stringify(tsconfig, null, 2)}\n`);
writeFile(
path.join(outputDir, "esbuild.config.mjs"),
`import esbuild from "esbuild";
import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
const watch = process.argv.includes("--watch");
const workerCtx = await esbuild.context(presets.esbuild.worker);
const manifestCtx = await esbuild.context(presets.esbuild.manifest);
const uiCtx = await esbuild.context(presets.esbuild.ui);
if (watch) {
await Promise.all([workerCtx.watch(), manifestCtx.watch(), uiCtx.watch()]);
console.log("esbuild watch mode enabled for worker, manifest, and ui");
} else {
await Promise.all([workerCtx.rebuild(), manifestCtx.rebuild(), uiCtx.rebuild()]);
await Promise.all([workerCtx.dispose(), manifestCtx.dispose(), uiCtx.dispose()]);
}
`,
);
writeFile(
path.join(outputDir, "rollup.config.mjs"),
`import { nodeResolve } from "@rollup/plugin-node-resolve";
import typescript from "@rollup/plugin-typescript";
import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
function withPlugins(config) {
if (!config) return null;
return {
...config,
plugins: [
nodeResolve({
extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs"],
}),
typescript({
tsconfig: "./tsconfig.json",
declaration: false,
declarationMap: false,
}),
],
};
}
export default [
withPlugins(presets.rollup.manifest),
withPlugins(presets.rollup.worker),
withPlugins(presets.rollup.ui),
].filter(Boolean);
`,
);
writeFile(
path.join(outputDir, "vitest.config.ts"),
`import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
include: ["tests/**/*.spec.ts"],
environment: "node",
},
});
`,
);
if (template === "environment") {
writeFile(
path.join(outputDir, "src", "manifest.ts"),
`import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
const manifest: PaperclipPluginManifestV1 = {
id: ${quote(manifestId)},
apiVersion: 1,
version: "0.1.0",
displayName: ${quote(displayName)},
description: ${quote(description)},
author: ${quote(author)},
categories: [${quote(category)}],
capabilities: [
"environment.drivers.register",
"plugin.state.read",
"plugin.state.write",
"ui.dashboardWidget.register"
],
entrypoints: {
worker: "./dist/worker.js",
ui: "./dist/ui"
},
environmentDrivers: [
{
driverKey: ${quote(manifestId + "-driver")},
displayName: ${quote(displayName + " Driver")}
}
],
ui: {
slots: [
{
type: "dashboardWidget",
id: "health-widget",
displayName: ${quote(`${displayName} Health`)},
exportName: "DashboardWidget"
}
]
}
};
export default manifest;
`,
);
writeFile(
path.join(outputDir, "src", "worker.ts"),
`import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
import type {
PluginEnvironmentValidateConfigParams,
PluginEnvironmentProbeParams,
PluginEnvironmentAcquireLeaseParams,
PluginEnvironmentResumeLeaseParams,
PluginEnvironmentReleaseLeaseParams,
PluginEnvironmentDestroyLeaseParams,
PluginEnvironmentRealizeWorkspaceParams,
PluginEnvironmentExecuteParams,
} from "@paperclipai/plugin-sdk";
const plugin = definePlugin({
async setup(ctx) {
ctx.data.register("health", async () => {
return { status: "ok", checkedAt: new Date().toISOString() };
});
},
async onHealth() {
return { status: "ok", message: "Environment plugin worker is running" };
},
async onEnvironmentValidateConfig(params: PluginEnvironmentValidateConfigParams) {
if (!params.config || typeof params.config !== "object") {
return { ok: false, errors: ["Config must be a non-null object"] };
}
return { ok: true, normalizedConfig: params.config };
},
async onEnvironmentProbe(_params: PluginEnvironmentProbeParams) {
return { ok: true, summary: "Environment is reachable" };
},
async onEnvironmentAcquireLease(params: PluginEnvironmentAcquireLeaseParams) {
const providerLeaseId = \`lease-\${params.runId}-\${Date.now()}\`;
return {
providerLeaseId,
metadata: { acquiredAt: new Date().toISOString() },
};
},
async onEnvironmentResumeLease(params: PluginEnvironmentResumeLeaseParams) {
return {
providerLeaseId: params.providerLeaseId,
metadata: { ...params.leaseMetadata, resumed: true },
};
},
async onEnvironmentReleaseLease(_params: PluginEnvironmentReleaseLeaseParams) {
// Release provider-side resources here
},
async onEnvironmentDestroyLease(_params: PluginEnvironmentDestroyLeaseParams) {
// Destroy provider-side resources here
},
async onEnvironmentRealizeWorkspace(params: PluginEnvironmentRealizeWorkspaceParams) {
const cwd = params.workspace.remotePath ?? params.workspace.localPath ?? "/tmp/workspace";
return { cwd, metadata: { realized: true } };
},
async onEnvironmentExecute(params: PluginEnvironmentExecuteParams) {
// Replace this with real command execution against your provider
return {
exitCode: 0,
timedOut: false,
stdout: \`Executed: \${params.command}\`,
stderr: "",
};
},
});
export default plugin;
runWorker(plugin, import.meta.url);
`,
);
writeFile(
path.join(outputDir, "src", "ui", "index.tsx"),
`import { usePluginData, type PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
type HealthData = {
status: "ok" | "degraded" | "error";
checkedAt: string;
};
export function DashboardWidget(_props: PluginWidgetProps) {
const { data, loading, error } = usePluginData<HealthData>("health");
if (loading) return <div>Loading environment health...</div>;
if (error) return <div>Plugin error: {error.message}</div>;
return (
<div style={{ display: "grid", gap: "0.5rem" }}>
<strong>${displayName}</strong>
<div>Health: {data?.status ?? "unknown"}</div>
<div>Checked: {data?.checkedAt ?? "never"}</div>
</div>
);
}
`,
);
writeFile(
path.join(outputDir, "tests", "plugin.spec.ts"),
`import { describe, expect, it } from "vitest";
import {
createEnvironmentTestHarness,
createFakeEnvironmentDriver,
assertEnvironmentEventOrder,
assertLeaseLifecycle,
} from "@paperclipai/plugin-sdk/testing";
import manifest from "../src/manifest.js";
import plugin from "../src/worker.js";
const ENV_ID = "env-test-1";
const BASE_PARAMS = {
driverKey: manifest.environmentDrivers![0].driverKey,
companyId: "co-1",
environmentId: ENV_ID,
config: {},
};
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 });
await plugin.definition.setup(harness.ctx);
const result = await plugin.definition.onEnvironmentValidateConfig!({
driverKey: BASE_PARAMS.driverKey,
config: { host: "test" },
});
expect(result.ok).toBe(true);
});
it("probes the environment", async () => {
const driver = createFakeEnvironmentDriver({ driverKey: BASE_PARAMS.driverKey });
const harness = createEnvironmentTestHarness({ manifest, environmentDriver: driver });
await plugin.definition.setup(harness.ctx);
const result = await plugin.definition.onEnvironmentProbe!(BASE_PARAMS);
expect(result.ok).toBe(true);
});
it("runs a full lease lifecycle through the harness", async () => {
const driver = createFakeEnvironmentDriver({ driverKey: BASE_PARAMS.driverKey });
const harness = createEnvironmentTestHarness({ manifest, environmentDriver: driver });
await plugin.definition.setup(harness.ctx);
const lease = await harness.acquireLease({ ...BASE_PARAMS, runId: "run-1" });
expect(lease.providerLeaseId).toBeTruthy();
await harness.realizeWorkspace({
...BASE_PARAMS,
lease,
workspace: { localPath: "/tmp/test" },
});
await harness.releaseLease({
...BASE_PARAMS,
providerLeaseId: lease.providerLeaseId,
});
assertEnvironmentEventOrder(harness.environmentEvents, [
"acquireLease",
"realizeWorkspace",
"releaseLease",
]);
assertLeaseLifecycle(harness.environmentEvents, ENV_ID);
});
});
`,
);
} else {
writeFile(
path.join(outputDir, "src", "manifest.ts"),
`import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
const manifest: PaperclipPluginManifestV1 = {
id: ${quote(manifestId)},
apiVersion: 1,
version: "0.1.0",
displayName: ${quote(displayName)},
description: ${quote(description)},
author: ${quote(author)},
categories: [${quote(category)}],
capabilities: [
"events.subscribe",
"plugin.state.read",
"plugin.state.write",
"ui.dashboardWidget.register"${template === "connector" ? `,
"connectors.provide"` : ""}
],
entrypoints: {
worker: "./dist/worker.js",
ui: "./dist/ui"
},${template === "connector" ? `
// A connector type for the Connectors catalog. It grants no tools by itself:
// an operator connects it and chooses which agents (or the whole company)
// can use its tools, exactly like a built-in connector.
apps: [
{
schemaVersion: 1,
slug: "records",
name: ${quote(displayName)},
description: "Look up records.",
categories: ["data"],
branding: { logoUrl: "/brands/apps/api-key-generic.svg" },
urlPatterns: [],
methods: [
{
key: "default",
label: "Connect",
transport: "plugin",
auth: "none",
ownershipModes: ["customer"],
whenToUse: "Look up records from this plugin.",
guidanceMd: "No sign-in is needed.",
riskTier: "S1",
settingsSchema: {
type: "object",
properties: { region: { type: "string", enum: ["us", "eu"] } },
additionalProperties: false
},
tools: {
kind: "static",
list: [
{
name: "lookup_record",
displayName: "Look up a record",
description: "Return one record by id.",
risk: "read",
parametersSchema: {
type: "object",
properties: { id: { type: "string" } },
required: ["id"]
}
}
]
}
}
]
}
],` : ""}
ui: {
slots: [
{
type: "dashboardWidget",
id: "health-widget",
displayName: ${quote(`${displayName} Health`)},
exportName: "DashboardWidget"
}
]
}
};
export default manifest;
`,
);
writeFile(
path.join(outputDir, "src", "worker.ts"),
`import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
const plugin = definePlugin({
async setup(ctx) {
ctx.events.on("issue.created", async (event) => {
const issueId = event.entityId ?? "unknown";
await ctx.state.set({ scopeKind: "issue", scopeId: issueId, stateKey: "seen" }, true);
ctx.logger.info("Observed issue.created", { issueId });
});
ctx.data.register("health", async () => {
return { status: "ok", checkedAt: new Date().toISOString() };
});
ctx.actions.register("ping", async () => {
ctx.logger.info("Ping action invoked");
return { pong: true, at: new Date().toISOString() };
});${template === "connector" ? `
// Each call runs on one connection. The host passes its settings (and,
// for authenticated methods, a credential for this call only).
ctx.connectors.register("records", "lookup_record", async (params, runCtx) => {
const { id } = params as { id: string };
const region = String(runCtx.connection.settings.region ?? "us");
return { content: \`Record \${id} (\${region})\`, data: { id, region } };
});` : ""}
},
async onHealth() {
return { status: "ok", message: "Plugin worker is running" };
}
});
export default plugin;
runWorker(plugin, import.meta.url);
`,
);
writeFile(
path.join(outputDir, "src", "ui", "index.tsx"),
`import { usePluginAction, usePluginData, type PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
type HealthData = {
status: "ok" | "degraded" | "error";
checkedAt: string;
};
export function DashboardWidget(_props: PluginWidgetProps) {
const { data, loading, error } = usePluginData<HealthData>("health");
const ping = usePluginAction("ping");
if (loading) return <div>Loading plugin health...</div>;
if (error) return <div>Plugin error: {error.message}</div>;
return (
<div style={{ display: "grid", gap: "0.5rem" }}>
<strong>${displayName}</strong>
<div>Health: {data?.status ?? "unknown"}</div>
<div>Checked: {data?.checkedAt ?? "never"}</div>
<button onClick={() => void ping()}>Ping Worker</button>
</div>
);
}
`,
);
writeFile(
path.join(outputDir, "tests", "plugin.spec.ts"),
`import { describe, expect, it } from "vitest";
import { createTestHarness } from "@paperclipai/plugin-sdk/testing";
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);
await harness.emit("issue.created", { issueId: "iss_1" }, { entityId: "iss_1", entityType: "issue" });
expect(harness.getState({ scopeKind: "issue", scopeId: "iss_1", stateKey: "seen" })).toBe(true);
const data = await harness.getData<{ status: string }>("health");
expect(data.status).toBe("ok");
const action = await harness.performAction<{ pong: boolean }>("ping");
expect(action.pong).toBe(true);
});${template === "connector" ? `
it("serves its connector tool on a connection", async () => {
const harness = createTestHarness({ manifest });
await plugin.definition.setup(harness.ctx);
const result = await harness.executeConnectorTool<{ data: { region: string } }>(
"records", "lookup_record", { id: "r1" }, { settings: { region: "eu" } },
);
expect(result.data.region).toBe("eu");
});` : ""}
});
`,
);
}
writeFile(
path.join(outputDir, "README.md"),
`# ${displayName}
${description}
## Development
\`\`\`bash
pnpm install
pnpm dev # watch builds
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`
: ""}
## Install Into Paperclip
\`\`\`bash
paperclipai plugin install ${shellQuote(toPosixPath(outputDir))}
\`\`\`
## Build Options
- \`pnpm build\` uses esbuild presets from \`@paperclipai/plugin-sdk/bundlers\`.
- \`pnpm build:rollup\` uses rollup presets from the same SDK.
`,
);
writeFile(path.join(outputDir, ".gitignore"), "dist\nnode_modules\n.paperclip-sdk\n");
return outputDir;
}