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
@@ -43,6 +43,7 @@ export const issuesApi = {
|
||||
workspaceId?: string;
|
||||
executionWorkspaceId?: string;
|
||||
originKind?: string;
|
||||
originKindPrefix?: string;
|
||||
originId?: string;
|
||||
descendantOf?: string;
|
||||
includeRoutineExecutions?: boolean;
|
||||
@@ -66,6 +67,7 @@ export const issuesApi = {
|
||||
if (filters?.workspaceId) params.set("workspaceId", filters.workspaceId);
|
||||
if (filters?.executionWorkspaceId) params.set("executionWorkspaceId", filters.executionWorkspaceId);
|
||||
if (filters?.originKind) params.set("originKind", filters.originKind);
|
||||
if (filters?.originKindPrefix) params.set("originKindPrefix", filters.originKindPrefix);
|
||||
if (filters?.originId) params.set("originId", filters.originId);
|
||||
if (filters?.descendantOf) params.set("descendantOf", filters.descendantOf);
|
||||
if (filters?.includeRoutineExecutions) params.set("includeRoutineExecutions", "true");
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mockApi = vi.hoisted(() => ({
|
||||
get: vi.fn(),
|
||||
post: vi.fn(),
|
||||
put: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("./client", () => ({
|
||||
api: mockApi,
|
||||
}));
|
||||
|
||||
import { pluginsApi } from "./plugins";
|
||||
|
||||
describe("pluginsApi local folders", () => {
|
||||
beforeEach(() => {
|
||||
mockApi.get.mockReset();
|
||||
mockApi.post.mockReset();
|
||||
mockApi.put.mockReset();
|
||||
mockApi.get.mockResolvedValue({});
|
||||
mockApi.post.mockResolvedValue({});
|
||||
mockApi.put.mockResolvedValue({});
|
||||
});
|
||||
|
||||
it("lists company-scoped local folders for a plugin", async () => {
|
||||
await pluginsApi.listLocalFolders("plugin-1", "company-1");
|
||||
|
||||
expect(mockApi.get).toHaveBeenCalledWith(
|
||||
"/plugins/plugin-1/companies/company-1/local-folders",
|
||||
);
|
||||
});
|
||||
|
||||
it("validates a candidate folder path without saving", async () => {
|
||||
await pluginsApi.validateLocalFolder("plugin-1", "company-1", "wiki-root", {
|
||||
path: "/tmp/wiki",
|
||||
access: "readWrite",
|
||||
requiredFiles: ["WIKI.md"],
|
||||
});
|
||||
|
||||
expect(mockApi.post).toHaveBeenCalledWith(
|
||||
"/plugins/plugin-1/companies/company-1/local-folders/wiki-root/validate",
|
||||
{
|
||||
path: "/tmp/wiki",
|
||||
access: "readWrite",
|
||||
requiredFiles: ["WIKI.md"],
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
it("saves through the local-folder PUT endpoint", async () => {
|
||||
await pluginsApi.configureLocalFolder("plugin-1", "company-1", "wiki-root", {
|
||||
path: "/tmp/wiki",
|
||||
requiredDirectories: ["wiki"],
|
||||
});
|
||||
|
||||
expect(mockApi.put).toHaveBeenCalledWith(
|
||||
"/plugins/plugin-1/companies/company-1/local-folders/wiki-root",
|
||||
{
|
||||
path: "/tmp/wiki",
|
||||
requiredDirectories: ["wiki"],
|
||||
},
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -14,6 +14,7 @@ import type {
|
||||
PluginLauncherDeclaration,
|
||||
PluginLauncherRenderContextSnapshot,
|
||||
PluginUiSlotDeclaration,
|
||||
PluginLocalFolderDeclaration,
|
||||
PluginRecord,
|
||||
PluginConfig,
|
||||
PluginStatus,
|
||||
@@ -140,6 +141,54 @@ export interface AvailablePluginExample {
|
||||
tag: "example";
|
||||
}
|
||||
|
||||
export interface PluginLocalFolderProblem {
|
||||
code:
|
||||
| "not_configured"
|
||||
| "not_absolute"
|
||||
| "missing"
|
||||
| "not_directory"
|
||||
| "not_readable"
|
||||
| "not_writable"
|
||||
| "missing_directory"
|
||||
| "missing_file"
|
||||
| "path_traversal"
|
||||
| "symlink_escape"
|
||||
| "atomic_write_failed";
|
||||
message: string;
|
||||
path?: string;
|
||||
}
|
||||
|
||||
export interface PluginLocalFolderStatus {
|
||||
folderKey: string;
|
||||
configured: boolean;
|
||||
path: string | null;
|
||||
realPath: string | null;
|
||||
access: "read" | "readWrite";
|
||||
readable: boolean;
|
||||
writable: boolean;
|
||||
requiredDirectories: string[];
|
||||
requiredFiles: string[];
|
||||
missingDirectories: string[];
|
||||
missingFiles: string[];
|
||||
healthy: boolean;
|
||||
problems: PluginLocalFolderProblem[];
|
||||
checkedAt: string;
|
||||
}
|
||||
|
||||
export interface PluginLocalFoldersResponse {
|
||||
pluginId: string;
|
||||
companyId: string;
|
||||
declarations: PluginLocalFolderDeclaration[];
|
||||
folders: PluginLocalFolderStatus[];
|
||||
}
|
||||
|
||||
export interface PluginLocalFolderSaveInput {
|
||||
path: string;
|
||||
access?: "read" | "readWrite";
|
||||
requiredDirectories?: string[];
|
||||
requiredFiles?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Plugin management API client.
|
||||
*
|
||||
@@ -337,6 +386,48 @@ export const pluginsApi = {
|
||||
testConfig: (pluginId: string, configJson: Record<string, unknown>) =>
|
||||
api.post<{ valid: boolean; message?: string }>(`/plugins/${pluginId}/config/test`, { configJson }),
|
||||
|
||||
/**
|
||||
* List manifest-declared and stored company-scoped local folders for a plugin.
|
||||
*/
|
||||
listLocalFolders: (pluginId: string, companyId: string) =>
|
||||
api.get<PluginLocalFoldersResponse>(`/plugins/${pluginId}/companies/${companyId}/local-folders`),
|
||||
|
||||
/**
|
||||
* Inspect a configured local folder without changing persisted settings.
|
||||
*/
|
||||
localFolderStatus: (pluginId: string, companyId: string, folderKey: string) =>
|
||||
api.get<PluginLocalFolderStatus>(
|
||||
`/plugins/${pluginId}/companies/${companyId}/local-folders/${encodeURIComponent(folderKey)}/status`,
|
||||
),
|
||||
|
||||
/**
|
||||
* Validate a candidate local folder path without saving it.
|
||||
*/
|
||||
validateLocalFolder: (
|
||||
pluginId: string,
|
||||
companyId: string,
|
||||
folderKey: string,
|
||||
input: PluginLocalFolderSaveInput,
|
||||
) =>
|
||||
api.post<PluginLocalFolderStatus>(
|
||||
`/plugins/${pluginId}/companies/${companyId}/local-folders/${encodeURIComponent(folderKey)}/validate`,
|
||||
input,
|
||||
),
|
||||
|
||||
/**
|
||||
* Persist a company-scoped local folder path and return its inspected status.
|
||||
*/
|
||||
configureLocalFolder: (
|
||||
pluginId: string,
|
||||
companyId: string,
|
||||
folderKey: string,
|
||||
input: PluginLocalFolderSaveInput,
|
||||
) =>
|
||||
api.put<PluginLocalFolderStatus>(
|
||||
`/plugins/${pluginId}/companies/${companyId}/local-folders/${encodeURIComponent(folderKey)}`,
|
||||
input,
|
||||
),
|
||||
|
||||
// ===========================================================================
|
||||
// Bridge proxy endpoints — used by the plugin UI bridge runtime
|
||||
// ===========================================================================
|
||||
|
||||
Reference in New Issue
Block a user