Expand plugin host surface (#5205)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - The plugin system is the extension boundary for optional product capabilities > - Rich plugins need more than a worker entrypoint: they need scoped database storage, local project folders, managed agents/routines, host navigation, and reusable UI components > - The LLM Wiki work exposed those missing host surfaces while keeping plugin code outside the core control plane > - This pull request expands the core plugin host, SDK, server APIs, and UI bridge so plugins can declare and use those surfaces > - The benefit is that future plugins can integrate with Paperclip through documented, validated contracts instead of bespoke server or UI imports ## What Changed - Added plugin-managed database namespaces and migration tracking, including Drizzle schema/migration files and SQL validation for namespace isolation. - Added server support for plugin local folders, managed agents, managed routines, scoped plugin APIs, and plugin operation visibility. - Expanded shared plugin manifest/types/validators and SDK host/testing/UI exports for richer plugin surfaces. - Added reusable UI pieces for file trees, managed routines, resizable sidebars, route sidebars, and plugin bridge initialization. - Updated plugin docs and example plugins to use the expanded host and SDK surface. ## Verification - `pnpm install --frozen-lockfile` - `pnpm run preflight:workspace-links && pnpm exec vitest run packages/shared/src/validators/plugin.test.ts server/src/__tests__/plugin-database.test.ts server/src/__tests__/plugin-local-folders.test.ts server/src/__tests__/plugin-managed-agents.test.ts server/src/__tests__/plugin-managed-routines.test.ts server/src/__tests__/plugin-orchestration-apis.test.ts ui/src/api/plugins.test.ts ui/src/components/FileTree.test.tsx ui/src/components/ResizableSidebarPane.test.tsx ui/src/pages/PluginPage.test.tsx ui/src/plugins/bridge.test.ts` passed: 11 files, 67 tests. - Confirmed this PR changes 89 files and does not include `pnpm-lock.yaml` or `.github/workflows/*`. ## Risks - Medium: this expands plugin host contracts across db/shared/server/ui and includes a new core migration (`0076_useful_elektra.sql`). - The plugin database namespace validator is intentionally restrictive; plugin authors may need follow-up affordances for SQL patterns that remain blocked. - Merge this before the LLM Wiki plugin PR so the plugin can resolve the new SDK and host APIs. > 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 - OpenAI Codex, GPT-5 coding agent, tool-enabled shell/git/GitHub workflow. Context window size was not exposed by the runtime. ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
@@ -12,6 +12,8 @@ const mockPluginsApi = vi.hoisted(() => ({
|
||||
dashboard: vi.fn(),
|
||||
logs: vi.fn(),
|
||||
getConfig: vi.fn(),
|
||||
listLocalFolders: vi.fn(),
|
||||
configureLocalFolder: vi.fn(),
|
||||
}));
|
||||
|
||||
const mockSetBreadcrumbs = vi.hoisted(() => vi.fn());
|
||||
@@ -58,6 +60,82 @@ async function flushReact() {
|
||||
});
|
||||
}
|
||||
|
||||
function basePlugin(overrides: Record<string, unknown> = {}) {
|
||||
return {
|
||||
id: "plugin-1",
|
||||
pluginKey: "paperclip.e2b-sandbox-provider",
|
||||
packageName: "@paperclipai/plugin-e2b",
|
||||
version: "0.1.0",
|
||||
status: "error",
|
||||
categories: ["automation"],
|
||||
manifestJson: {
|
||||
displayName: "E2B Sandbox Provider",
|
||||
version: "0.1.0",
|
||||
description: "E2B environments for Paperclip.",
|
||||
author: "Paperclip",
|
||||
capabilities: ["environment.drivers.register"],
|
||||
environmentDrivers: [
|
||||
{
|
||||
driverKey: "e2b",
|
||||
kind: "sandbox_provider",
|
||||
displayName: "E2B Cloud Sandbox",
|
||||
},
|
||||
],
|
||||
},
|
||||
lastError: null,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function wikiFolderDeclaration() {
|
||||
return {
|
||||
folderKey: "wiki-root",
|
||||
displayName: "Wiki root",
|
||||
description: "Company-scoped local folder that stores wiki files.",
|
||||
access: "readWrite" as const,
|
||||
requiredDirectories: ["raw", "wiki"],
|
||||
requiredFiles: ["WIKI.md", "index.md"],
|
||||
};
|
||||
}
|
||||
|
||||
function folderStatus(overrides: Record<string, unknown> = {}) {
|
||||
return {
|
||||
folderKey: "wiki-root",
|
||||
configured: false,
|
||||
path: null,
|
||||
realPath: null,
|
||||
access: "readWrite",
|
||||
readable: false,
|
||||
writable: false,
|
||||
requiredDirectories: ["raw", "wiki"],
|
||||
requiredFiles: ["WIKI.md", "index.md"],
|
||||
missingDirectories: ["raw", "wiki"],
|
||||
missingFiles: ["WIKI.md", "index.md"],
|
||||
healthy: false,
|
||||
problems: [{ code: "not_configured", message: "No local folder path is configured." }],
|
||||
checkedAt: "2026-05-02T16:00:00.000Z",
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
async function renderSettings(container: HTMLDivElement) {
|
||||
const root = createRoot(container);
|
||||
const queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { retry: false } },
|
||||
});
|
||||
|
||||
await act(async () => {
|
||||
root.render(
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<PluginSettings />
|
||||
</QueryClientProvider>,
|
||||
);
|
||||
});
|
||||
await flushReact();
|
||||
await flushReact();
|
||||
return root;
|
||||
}
|
||||
|
||||
describe("PluginSettings", () => {
|
||||
let container: HTMLDivElement;
|
||||
|
||||
@@ -65,30 +143,16 @@ describe("PluginSettings", () => {
|
||||
container = document.createElement("div");
|
||||
document.body.appendChild(container);
|
||||
|
||||
mockPluginsApi.get.mockResolvedValue({
|
||||
id: "plugin-1",
|
||||
pluginKey: "paperclip.e2b-sandbox-provider",
|
||||
packageName: "@paperclipai/plugin-e2b",
|
||||
version: "0.1.0",
|
||||
status: "error",
|
||||
categories: ["automation"],
|
||||
manifestJson: {
|
||||
displayName: "E2B Sandbox Provider",
|
||||
version: "0.1.0",
|
||||
description: "E2B environments for Paperclip.",
|
||||
author: "Paperclip",
|
||||
capabilities: ["environment.drivers.register"],
|
||||
environmentDrivers: [
|
||||
{
|
||||
driverKey: "e2b",
|
||||
kind: "sandbox_provider",
|
||||
displayName: "E2B Cloud Sandbox",
|
||||
},
|
||||
],
|
||||
},
|
||||
lastError: null,
|
||||
});
|
||||
mockPluginsApi.get.mockResolvedValue(basePlugin());
|
||||
mockPluginsApi.dashboard.mockResolvedValue(null);
|
||||
mockPluginsApi.health.mockResolvedValue({ pluginId: "plugin-1", status: "ready", healthy: true, checks: [] });
|
||||
mockPluginsApi.logs.mockResolvedValue([]);
|
||||
mockPluginsApi.listLocalFolders.mockResolvedValue({
|
||||
pluginId: "plugin-1",
|
||||
companyId: "company-1",
|
||||
declarations: [],
|
||||
folders: [],
|
||||
});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
@@ -98,20 +162,7 @@ describe("PluginSettings", () => {
|
||||
});
|
||||
|
||||
it("routes environment-provider plugins to company environments when they have no instance config", async () => {
|
||||
const root = createRoot(container);
|
||||
const queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { retry: false } },
|
||||
});
|
||||
|
||||
await act(async () => {
|
||||
root.render(
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<PluginSettings />
|
||||
</QueryClientProvider>,
|
||||
);
|
||||
});
|
||||
await flushReact();
|
||||
await flushReact();
|
||||
const root = await renderSettings(container);
|
||||
|
||||
expect(container.textContent).toContain("Configure this plugin from Company Environments.");
|
||||
expect(container.textContent).toContain("company-scoped instead of instance-global");
|
||||
@@ -122,4 +173,165 @@ describe("PluginSettings", () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("renders unconfigured manifest local folders with required paths", async () => {
|
||||
const declaration = wikiFolderDeclaration();
|
||||
mockPluginsApi.get.mockResolvedValue(basePlugin({
|
||||
pluginKey: "paperclipai.plugin-llm-wiki",
|
||||
packageName: "@paperclipai/plugin-llm-wiki",
|
||||
status: "ready",
|
||||
manifestJson: {
|
||||
displayName: "LLM Wiki",
|
||||
version: "0.1.0",
|
||||
description: "Local-file LLM Wiki plugin.",
|
||||
author: "Paperclip",
|
||||
capabilities: ["local.folders"],
|
||||
localFolders: [declaration],
|
||||
},
|
||||
}));
|
||||
mockPluginsApi.listLocalFolders.mockResolvedValue({
|
||||
pluginId: "plugin-1",
|
||||
companyId: "company-1",
|
||||
declarations: [declaration],
|
||||
folders: [folderStatus()],
|
||||
});
|
||||
|
||||
const root = await renderSettings(container);
|
||||
|
||||
expect(container.textContent).toContain("Local folders");
|
||||
expect(container.textContent).toContain("Wiki root");
|
||||
expect(container.textContent).toContain("Needs attention");
|
||||
expect(container.textContent).toContain("No local folder path is configured.");
|
||||
expect(container.textContent).toContain("Missing directories: raw, wiki");
|
||||
expect(container.textContent).toContain("Missing files: WIKI.md, index.md");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("renders invalid configured folders with validation problems", async () => {
|
||||
const declaration = wikiFolderDeclaration();
|
||||
mockPluginsApi.get.mockResolvedValue(basePlugin({
|
||||
manifestJson: {
|
||||
displayName: "LLM Wiki",
|
||||
version: "0.1.0",
|
||||
description: "Local-file LLM Wiki plugin.",
|
||||
author: "Paperclip",
|
||||
capabilities: ["local.folders"],
|
||||
localFolders: [declaration],
|
||||
},
|
||||
}));
|
||||
mockPluginsApi.listLocalFolders.mockResolvedValue({
|
||||
pluginId: "plugin-1",
|
||||
companyId: "company-1",
|
||||
declarations: [declaration],
|
||||
folders: [folderStatus({
|
||||
configured: true,
|
||||
path: "/tmp/wiki",
|
||||
realPath: "/tmp/wiki",
|
||||
readable: true,
|
||||
writable: true,
|
||||
missingDirectories: [],
|
||||
missingFiles: ["WIKI.md"],
|
||||
problems: [{ code: "missing_file", message: "Required file is missing.", path: "WIKI.md" }],
|
||||
})],
|
||||
});
|
||||
|
||||
const root = await renderSettings(container);
|
||||
|
||||
expect(container.textContent).toContain("/tmp/wiki");
|
||||
expect(container.textContent).toContain("ReadableYes");
|
||||
expect(container.textContent).toContain("WritableYes");
|
||||
expect(container.textContent).toContain("Validation problems");
|
||||
expect(container.textContent).toContain("Required file is missing.");
|
||||
expect(container.textContent).toContain("Missing files: WIKI.md");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("does not render required paths as present when the configured root cannot be inspected", async () => {
|
||||
const declaration = wikiFolderDeclaration();
|
||||
mockPluginsApi.get.mockResolvedValue(basePlugin({
|
||||
manifestJson: {
|
||||
displayName: "LLM Wiki",
|
||||
version: "0.1.0",
|
||||
description: "Local-file LLM Wiki plugin.",
|
||||
author: "Paperclip",
|
||||
capabilities: ["local.folders"],
|
||||
localFolders: [declaration],
|
||||
},
|
||||
}));
|
||||
mockPluginsApi.listLocalFolders.mockResolvedValue({
|
||||
pluginId: "plugin-1",
|
||||
companyId: "company-1",
|
||||
declarations: [declaration],
|
||||
folders: [folderStatus({
|
||||
configured: true,
|
||||
path: "/tmp/wiki-missing",
|
||||
readable: false,
|
||||
writable: false,
|
||||
missingDirectories: [],
|
||||
missingFiles: [],
|
||||
problems: [{ code: "missing", message: "Configured local folder cannot be inspected.", path: "/tmp/wiki-missing" }],
|
||||
})],
|
||||
});
|
||||
|
||||
const root = await renderSettings(container);
|
||||
|
||||
expect(container.textContent).toContain("Configured local folder cannot be inspected.");
|
||||
expect(container.textContent).toContain("Not inspected");
|
||||
expect(container.textContent).toContain("Configured root was not inspected.");
|
||||
expect(container.textContent).not.toContain("Present");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("renders healthy folders without validation problems", async () => {
|
||||
const declaration = wikiFolderDeclaration();
|
||||
mockPluginsApi.get.mockResolvedValue(basePlugin({
|
||||
manifestJson: {
|
||||
displayName: "LLM Wiki",
|
||||
version: "0.1.0",
|
||||
description: "Local-file LLM Wiki plugin.",
|
||||
author: "Paperclip",
|
||||
capabilities: ["local.folders"],
|
||||
localFolders: [declaration],
|
||||
},
|
||||
}));
|
||||
mockPluginsApi.listLocalFolders.mockResolvedValue({
|
||||
pluginId: "plugin-1",
|
||||
companyId: "company-1",
|
||||
declarations: [declaration],
|
||||
folders: [folderStatus({
|
||||
configured: true,
|
||||
path: "/tmp/wiki",
|
||||
realPath: "/private/tmp/wiki",
|
||||
readable: true,
|
||||
writable: true,
|
||||
missingDirectories: [],
|
||||
missingFiles: [],
|
||||
healthy: true,
|
||||
problems: [],
|
||||
})],
|
||||
});
|
||||
|
||||
const root = await renderSettings(container);
|
||||
|
||||
expect(container.textContent).toContain("Healthy");
|
||||
expect(container.textContent).toContain("Configured path");
|
||||
expect(container.textContent).toContain("/tmp/wiki");
|
||||
expect(container.textContent).toContain("ReadableYes");
|
||||
expect(container.textContent).toContain("WritableYes");
|
||||
expect(container.textContent).toContain("Present");
|
||||
expect(container.textContent).not.toContain("Validation problems");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user