forked from farhoodlabs/paperclip
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
@@ -17,6 +17,16 @@ const mockInstanceSettingsApi = vi.hoisted(() => ({
|
||||
const mockNavigate = vi.hoisted(() => vi.fn());
|
||||
const mockSetSelectedCompanyId = vi.hoisted(() => vi.fn());
|
||||
const mockSetSidebarOpen = vi.hoisted(() => vi.fn());
|
||||
const mockCompanyState = vi.hoisted(() => ({
|
||||
companies: [{ id: "company-1", issuePrefix: "PAP", name: "Paperclip" }],
|
||||
selectedCompany: { id: "company-1", issuePrefix: "PAP", name: "Paperclip" },
|
||||
selectedCompanyId: "company-1",
|
||||
}));
|
||||
const mockPluginSlots = vi.hoisted(() => ({
|
||||
slots: [] as Array<Record<string, unknown>>,
|
||||
}));
|
||||
const mockUsePluginSlots = vi.hoisted(() => vi.fn());
|
||||
const mockPluginSlotContexts = vi.hoisted(() => [] as Array<Record<string, unknown>>);
|
||||
let currentPathname = "/PAP/dashboard";
|
||||
|
||||
vi.mock("@/lib/router", () => ({
|
||||
@@ -24,7 +34,10 @@ vi.mock("@/lib/router", () => ({
|
||||
useLocation: () => ({ pathname: currentPathname, search: "", hash: "", state: null }),
|
||||
useNavigate: () => mockNavigate,
|
||||
useNavigationType: () => "PUSH",
|
||||
useParams: () => ({ companyPrefix: "PAP" }),
|
||||
useParams: () => {
|
||||
const firstSegment = currentPathname.split("/").filter(Boolean)[0];
|
||||
return { companyPrefix: firstSegment === "instance" ? undefined : firstSegment ?? "PAP" };
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock("./CompanyRail", () => ({
|
||||
@@ -95,6 +108,33 @@ vi.mock("./SidebarAccountMenu", () => ({
|
||||
SidebarAccountMenu: () => <div>Account menu</div>,
|
||||
}));
|
||||
|
||||
vi.mock("../plugins/slots", async () => {
|
||||
const actual = await vi.importActual<typeof import("../plugins/slots")>("../plugins/slots");
|
||||
return {
|
||||
resolveRouteSidebarSlot: actual.resolveRouteSidebarSlot,
|
||||
usePluginSlots: (params: Record<string, unknown>) => {
|
||||
mockUsePluginSlots(params);
|
||||
return {
|
||||
slots: mockPluginSlots.slots,
|
||||
isLoading: false,
|
||||
errorMessage: null,
|
||||
};
|
||||
},
|
||||
PluginSlotMount: ({
|
||||
slot,
|
||||
context,
|
||||
className,
|
||||
}: {
|
||||
slot: { displayName: string };
|
||||
context: Record<string, unknown>;
|
||||
className?: string;
|
||||
}) => {
|
||||
mockPluginSlotContexts.push(context);
|
||||
return <div data-plugin-slot-class={className}>Plugin route sidebar: {slot.displayName}</div>;
|
||||
},
|
||||
};
|
||||
});
|
||||
|
||||
vi.mock("../context/DialogContext", () => ({
|
||||
useDialog: () => ({
|
||||
openNewIssue: vi.fn(),
|
||||
@@ -114,10 +154,10 @@ vi.mock("../context/PanelContext", () => ({
|
||||
|
||||
vi.mock("../context/CompanyContext", () => ({
|
||||
useCompany: () => ({
|
||||
companies: [{ id: "company-1", issuePrefix: "PAP", name: "Paperclip" }],
|
||||
companies: mockCompanyState.companies,
|
||||
loading: false,
|
||||
selectedCompany: { id: "company-1", issuePrefix: "PAP", name: "Paperclip" },
|
||||
selectedCompanyId: "company-1",
|
||||
selectedCompany: mockCompanyState.selectedCompany,
|
||||
selectedCompanyId: mockCompanyState.selectedCompanyId,
|
||||
selectionSource: "manual",
|
||||
setSelectedCompanyId: mockSetSelectedCompanyId,
|
||||
}),
|
||||
@@ -179,6 +219,9 @@ describe("Layout", () => {
|
||||
container = document.createElement("div");
|
||||
document.body.appendChild(container);
|
||||
currentPathname = "/PAP/dashboard";
|
||||
mockCompanyState.companies = [{ id: "company-1", issuePrefix: "PAP", name: "Paperclip" }];
|
||||
mockCompanyState.selectedCompany = { id: "company-1", issuePrefix: "PAP", name: "Paperclip" };
|
||||
mockCompanyState.selectedCompanyId = "company-1";
|
||||
mockHealthApi.get.mockResolvedValue({
|
||||
status: "ok",
|
||||
deploymentMode: "authenticated",
|
||||
@@ -188,6 +231,8 @@ describe("Layout", () => {
|
||||
mockInstanceSettingsApi.getGeneral.mockResolvedValue({
|
||||
keyboardShortcuts: false,
|
||||
});
|
||||
mockPluginSlots.slots = [];
|
||||
mockPluginSlotContexts.length = 0;
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
@@ -227,6 +272,30 @@ describe("Layout", () => {
|
||||
|
||||
it("renders the company settings sidebar on company settings routes", async () => {
|
||||
currentPathname = "/PAP/company/settings/access";
|
||||
mockPluginSlots.slots = [
|
||||
{
|
||||
type: "page",
|
||||
id: "company-page",
|
||||
displayName: "Company Page",
|
||||
exportName: "CompanyPage",
|
||||
routePath: "company",
|
||||
pluginId: "plugin-1",
|
||||
pluginKey: "fake-plugin",
|
||||
pluginDisplayName: "Fake Plugin",
|
||||
pluginVersion: "1.0.0",
|
||||
},
|
||||
{
|
||||
type: "routeSidebar",
|
||||
id: "company-sidebar",
|
||||
displayName: "Company Route Sidebar",
|
||||
exportName: "CompanySidebar",
|
||||
routePath: "company",
|
||||
pluginId: "plugin-1",
|
||||
pluginKey: "fake-plugin",
|
||||
pluginDisplayName: "Fake Plugin",
|
||||
pluginVersion: "1.0.0",
|
||||
},
|
||||
];
|
||||
const root = createRoot(container);
|
||||
const queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { retry: false } },
|
||||
@@ -245,6 +314,213 @@ describe("Layout", () => {
|
||||
expect(container.textContent).toContain("Company settings sidebar");
|
||||
expect(container.textContent).not.toContain("Instance sidebar");
|
||||
expect(container.textContent).not.toContain("Main company nav");
|
||||
expect(container.textContent).not.toContain("Plugin route sidebar");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("renders the instance settings sidebar on instance settings routes", async () => {
|
||||
currentPathname = "/instance/settings/general";
|
||||
const root = createRoot(container);
|
||||
const queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { retry: false } },
|
||||
});
|
||||
|
||||
await act(async () => {
|
||||
root.render(
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<Layout />
|
||||
</QueryClientProvider>,
|
||||
);
|
||||
});
|
||||
await flushReact();
|
||||
await flushReact();
|
||||
|
||||
expect(container.textContent).toContain("Instance sidebar");
|
||||
expect(container.textContent).not.toContain("Company settings sidebar");
|
||||
expect(container.textContent).not.toContain("Main company nav");
|
||||
expect(container.textContent).not.toContain("Plugin route sidebar");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("renders a route-scoped plugin sidebar for a matching plugin page route", async () => {
|
||||
currentPathname = "/PAP/wiki";
|
||||
mockPluginSlots.slots = [
|
||||
{
|
||||
type: "page",
|
||||
id: "wiki-page",
|
||||
displayName: "Wiki Page",
|
||||
exportName: "WikiPage",
|
||||
routePath: "wiki",
|
||||
pluginId: "plugin-1",
|
||||
pluginKey: "wiki-plugin",
|
||||
pluginDisplayName: "Wiki Plugin",
|
||||
pluginVersion: "1.0.0",
|
||||
},
|
||||
{
|
||||
type: "routeSidebar",
|
||||
id: "wiki-route-sidebar",
|
||||
displayName: "Wiki Sidebar",
|
||||
exportName: "WikiSidebar",
|
||||
routePath: "wiki",
|
||||
pluginId: "plugin-1",
|
||||
pluginKey: "wiki-plugin",
|
||||
pluginDisplayName: "Wiki Plugin",
|
||||
pluginVersion: "1.0.0",
|
||||
},
|
||||
];
|
||||
const root = createRoot(container);
|
||||
const queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { retry: false } },
|
||||
});
|
||||
|
||||
await act(async () => {
|
||||
root.render(
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<Layout />
|
||||
</QueryClientProvider>,
|
||||
);
|
||||
});
|
||||
await flushReact();
|
||||
await flushReact();
|
||||
|
||||
expect(container.textContent).toContain("Plugin route sidebar: Wiki Sidebar");
|
||||
expect(container.querySelector("[data-plugin-slot-class='h-full w-full']")).not.toBeNull();
|
||||
expect(container.textContent).not.toContain("Main company nav");
|
||||
expect(container.textContent).not.toContain("Company settings sidebar");
|
||||
expect(container.textContent).not.toContain("Instance sidebar");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("uses the route company context for plugin route sidebars on the first render", async () => {
|
||||
currentPathname = "/ALT/wiki";
|
||||
mockCompanyState.companies = [
|
||||
{ id: "company-1", issuePrefix: "PAP", name: "Paperclip" },
|
||||
{ id: "company-2", issuePrefix: "ALT", name: "Alternate" },
|
||||
];
|
||||
mockCompanyState.selectedCompany = { id: "company-1", issuePrefix: "PAP", name: "Paperclip" };
|
||||
mockCompanyState.selectedCompanyId = "company-1";
|
||||
mockPluginSlots.slots = [
|
||||
{
|
||||
type: "page",
|
||||
id: "wiki-page",
|
||||
displayName: "Wiki Page",
|
||||
exportName: "WikiPage",
|
||||
routePath: "wiki",
|
||||
pluginId: "plugin-1",
|
||||
pluginKey: "wiki-plugin",
|
||||
pluginDisplayName: "Wiki Plugin",
|
||||
pluginVersion: "1.0.0",
|
||||
},
|
||||
{
|
||||
type: "routeSidebar",
|
||||
id: "wiki-route-sidebar",
|
||||
displayName: "Wiki Sidebar",
|
||||
exportName: "WikiSidebar",
|
||||
routePath: "wiki",
|
||||
pluginId: "plugin-1",
|
||||
pluginKey: "wiki-plugin",
|
||||
pluginDisplayName: "Wiki Plugin",
|
||||
pluginVersion: "1.0.0",
|
||||
},
|
||||
];
|
||||
const root = createRoot(container);
|
||||
const queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { retry: false } },
|
||||
});
|
||||
|
||||
await act(async () => {
|
||||
root.render(
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<Layout />
|
||||
</QueryClientProvider>,
|
||||
);
|
||||
});
|
||||
await flushReact();
|
||||
await flushReact();
|
||||
|
||||
expect(mockUsePluginSlots).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
companyId: "company-2",
|
||||
enabled: true,
|
||||
}),
|
||||
);
|
||||
expect(mockPluginSlotContexts).toContainEqual({
|
||||
companyId: "company-2",
|
||||
companyPrefix: "ALT",
|
||||
});
|
||||
expect(mockPluginSlotContexts).not.toContainEqual({
|
||||
companyId: "company-1",
|
||||
companyPrefix: "PAP",
|
||||
});
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
});
|
||||
});
|
||||
|
||||
it("keeps the normal company sidebar when a plugin page route is ambiguous", async () => {
|
||||
currentPathname = "/PAP/wiki";
|
||||
mockPluginSlots.slots = [
|
||||
{
|
||||
type: "page",
|
||||
id: "wiki-page-a",
|
||||
displayName: "Wiki Page A",
|
||||
exportName: "WikiPageA",
|
||||
routePath: "wiki",
|
||||
pluginId: "plugin-1",
|
||||
pluginKey: "wiki-plugin-a",
|
||||
pluginDisplayName: "Wiki Plugin A",
|
||||
pluginVersion: "1.0.0",
|
||||
},
|
||||
{
|
||||
type: "page",
|
||||
id: "wiki-page-b",
|
||||
displayName: "Wiki Page B",
|
||||
exportName: "WikiPageB",
|
||||
routePath: "wiki",
|
||||
pluginId: "plugin-2",
|
||||
pluginKey: "wiki-plugin-b",
|
||||
pluginDisplayName: "Wiki Plugin B",
|
||||
pluginVersion: "1.0.0",
|
||||
},
|
||||
{
|
||||
type: "routeSidebar",
|
||||
id: "wiki-route-sidebar",
|
||||
displayName: "Wiki Sidebar",
|
||||
exportName: "WikiSidebar",
|
||||
routePath: "wiki",
|
||||
pluginId: "plugin-1",
|
||||
pluginKey: "wiki-plugin-a",
|
||||
pluginDisplayName: "Wiki Plugin A",
|
||||
pluginVersion: "1.0.0",
|
||||
},
|
||||
];
|
||||
const root = createRoot(container);
|
||||
const queryClient = new QueryClient({
|
||||
defaultOptions: { queries: { retry: false } },
|
||||
});
|
||||
|
||||
await act(async () => {
|
||||
root.render(
|
||||
<QueryClientProvider client={queryClient}>
|
||||
<Layout />
|
||||
</QueryClientProvider>,
|
||||
);
|
||||
});
|
||||
await flushReact();
|
||||
await flushReact();
|
||||
|
||||
expect(container.textContent).toContain("Main company nav");
|
||||
expect(container.textContent).not.toContain("Plugin route sidebar");
|
||||
|
||||
await act(async () => {
|
||||
root.unmount();
|
||||
|
||||
Reference in New Issue
Block a user