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
@@ -0,0 +1,207 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import { act } from "react";
|
||||
import { createRoot } from "react-dom/client";
|
||||
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { PluginPage } from "./PluginPage";
|
||||
|
||||
const mockPluginsApi = vi.hoisted(() => ({
|
||||
listUiContributions: vi.fn(),
|
||||
}));
|
||||
|
||||
const mockSetBreadcrumbs = vi.hoisted(() => vi.fn());
|
||||
const mockParams = vi.hoisted(() => ({
|
||||
companyPrefix: "PAP" as string | undefined,
|
||||
pluginId: undefined as string | undefined,
|
||||
pluginRoutePath: undefined as string | undefined,
|
||||
"*": undefined as string | undefined,
|
||||
}));
|
||||
|
||||
vi.mock("@/api/plugins", () => ({
|
||||
pluginsApi: mockPluginsApi,
|
||||
}));
|
||||
|
||||
vi.mock("@/context/BreadcrumbContext", () => ({
|
||||
useBreadcrumbs: () => ({
|
||||
setBreadcrumbs: mockSetBreadcrumbs,
|
||||
}),
|
||||
}));
|
||||
|
||||
vi.mock("@/context/CompanyContext", () => ({
|
||||
useCompany: () => ({
|
||||
companies: [{ id: "company-1", name: "Paperclip", issuePrefix: "PAP" }],
|
||||
selectedCompanyId: "company-1",
|
||||
}),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/router", () => ({
|
||||
Link: ({ to, children }: { to: string; children: React.ReactNode }) => <a href={to}>{children}</a>,
|
||||
Navigate: () => null,
|
||||
useParams: () => mockParams,
|
||||
}));
|
||||
|
||||
vi.mock("@/plugins/slots", async () => {
|
||||
const actual = await vi.importActual<typeof import("@/plugins/slots")>("@/plugins/slots");
|
||||
return {
|
||||
resolveRouteSidebarSlot: actual.resolveRouteSidebarSlot,
|
||||
PluginSlotMount: ({ slot }: { slot: { displayName: string } }) => (
|
||||
<div data-testid="plugin-slot-mount">{slot.displayName}</div>
|
||||
),
|
||||
};
|
||||
});
|
||||
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
|
||||
|
||||
async function flushReact() {
|
||||
await act(async () => {
|
||||
await Promise.resolve();
|
||||
await new Promise((resolve) => window.setTimeout(resolve, 0));
|
||||
});
|
||||
}
|
||||
|
||||
function pageContribution(overrides: Partial<{ slots: unknown[] }> = {}) {
|
||||
return {
|
||||
pluginId: "plugin-wiki",
|
||||
pluginKey: "paperclipai.plugin-llm-wiki",
|
||||
displayName: "LLM Wiki",
|
||||
version: "0.1.0",
|
||||
uiEntryFile: "ui.js",
|
||||
slots: [
|
||||
{
|
||||
type: "page",
|
||||
id: "wiki-page",
|
||||
displayName: "Wiki",
|
||||
exportName: "WikiPage",
|
||||
routePath: "wiki",
|
||||
},
|
||||
],
|
||||
launchers: [],
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
async function renderPage(container: HTMLDivElement) {
|
||||
const root = createRoot(container);
|
||||
const queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { retry: false } },
|
||||
});
|
||||
|
||||
await act(async () => {
|
||||
root.render(
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<PluginPage />
|
||||
</QueryClientProvider>,
|
||||
);
|
||||
});
|
||||
await flushReact();
|
||||
await flushReact();
|
||||
return root;
|
||||
}
|
||||
|
||||
describe("PluginPage", () => {
|
||||
let container: HTMLDivElement;
|
||||
|
||||
beforeEach(() => {
|
||||
container = document.createElement("div");
|
||||
document.body.appendChild(container);
|
||||
mockParams.companyPrefix = "PAP";
|
||||
mockParams.pluginId = undefined;
|
||||
mockParams.pluginRoutePath = undefined;
|
||||
mockParams["*"] = undefined;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
container.remove();
|
||||
document.body.innerHTML = "";
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it("renders the breadcrumb and Back button on a legacy plugin route (no routeSidebar)", async () => {
|
||||
mockParams.pluginRoutePath = "wiki";
|
||||
mockPluginsApi.listUiContributions.mockResolvedValue([pageContribution()]);
|
||||
|
||||
const root = await renderPage(container);
|
||||
|
||||
expect(mockSetBreadcrumbs).toHaveBeenCalledWith([
|
||||
{ label: "Plugins", href: "/instance/settings/plugins" },
|
||||
{ label: "LLM Wiki" },
|
||||
]);
|
||||
expect(container.textContent).toContain("Back");
|
||||
expect(container.querySelector('a[href="/PAP/dashboard"]')).not.toBeNull();
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("uses a route title and hides the Back button when a routeSidebar matches the active route", async () => {
|
||||
mockParams.pluginRoutePath = "wiki";
|
||||
mockPluginsApi.listUiContributions.mockResolvedValue([
|
||||
pageContribution({
|
||||
slots: [
|
||||
{
|
||||
type: "page",
|
||||
id: "wiki-page",
|
||||
displayName: "Wiki",
|
||||
exportName: "WikiPage",
|
||||
routePath: "wiki",
|
||||
},
|
||||
{
|
||||
type: "routeSidebar",
|
||||
id: "wiki-sidebar",
|
||||
displayName: "Wiki Sidebar",
|
||||
exportName: "WikiRouteSidebar",
|
||||
routePath: "wiki",
|
||||
},
|
||||
],
|
||||
}),
|
||||
]);
|
||||
|
||||
const root = await renderPage(container);
|
||||
|
||||
expect(mockSetBreadcrumbs).toHaveBeenCalledWith([{ label: "Wiki" }]);
|
||||
expect(container.textContent).not.toContain("Back");
|
||||
expect(container.querySelector('a[href="/PAP/dashboard"]')).toBeNull();
|
||||
// Page slot itself still renders.
|
||||
expect(container.querySelector('[data-testid="plugin-slot-mount"]')?.textContent).toBe("Wiki");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("uses the selected plugin page path as the route-sidebar title", async () => {
|
||||
mockParams.pluginRoutePath = "wiki";
|
||||
mockParams["*"] = "page/templates%3A%3Aindex.md";
|
||||
mockPluginsApi.listUiContributions.mockResolvedValue([
|
||||
pageContribution({
|
||||
slots: [
|
||||
{
|
||||
type: "page",
|
||||
id: "wiki-page",
|
||||
displayName: "Wiki",
|
||||
exportName: "WikiPage",
|
||||
routePath: "wiki",
|
||||
},
|
||||
{
|
||||
type: "routeSidebar",
|
||||
id: "wiki-sidebar",
|
||||
displayName: "Wiki Sidebar",
|
||||
exportName: "WikiRouteSidebar",
|
||||
routePath: "wiki",
|
||||
},
|
||||
],
|
||||
}),
|
||||
]);
|
||||
|
||||
const root = await renderPage(container);
|
||||
|
||||
expect(mockSetBreadcrumbs).toHaveBeenCalledWith([{ label: "index" }]);
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user