mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-19 20:10:39 +09:00
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
GitHub
parent
d6bee62f02
commit
3c73ed26b5
89 changed files with 27516 additions and 914 deletions
263
server/src/__tests__/plugin-local-folders.test.ts
Normal file
263
server/src/__tests__/plugin-local-folders.test.ts
Normal file
|
|
@ -0,0 +1,263 @@
|
|||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import { promises as fs } from "node:fs";
|
||||
import {
|
||||
assertConfiguredLocalFolder,
|
||||
assertWritableConfiguredLocalFolder,
|
||||
inspectPluginLocalFolder,
|
||||
listPluginLocalFolderEntries,
|
||||
preparePluginLocalFolder,
|
||||
readPluginLocalFolderText,
|
||||
resolvePluginLocalFolderPath,
|
||||
writePluginLocalFolderTextAtomic,
|
||||
} from "../services/plugin-local-folders.js";
|
||||
|
||||
describe("plugin local folders", () => {
|
||||
const tempRoots: string[] = [];
|
||||
|
||||
afterEach(async () => {
|
||||
await Promise.all(tempRoots.map((root) => fs.rm(root, { recursive: true, force: true })));
|
||||
tempRoots.length = 0;
|
||||
});
|
||||
|
||||
async function makeRoot() {
|
||||
const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-plugin-folder-"));
|
||||
tempRoots.push(root);
|
||||
return root;
|
||||
}
|
||||
|
||||
it("reports a healthy generic folder when required paths exist", async () => {
|
||||
const root = await makeRoot();
|
||||
await fs.mkdir(path.join(root, "sources"));
|
||||
await fs.writeFile(path.join(root, "schema.md"), "schema", "utf8");
|
||||
|
||||
const status = await inspectPluginLocalFolder({
|
||||
folderKey: "content-root",
|
||||
storedConfig: {
|
||||
path: root,
|
||||
access: "readWrite",
|
||||
requiredDirectories: ["sources"],
|
||||
requiredFiles: ["schema.md"],
|
||||
},
|
||||
});
|
||||
|
||||
expect(status.healthy).toBe(true);
|
||||
expect(status.problems).toEqual([]);
|
||||
expect(status.requiredDirectories).toEqual(["sources"]);
|
||||
expect(status.requiredFiles).toEqual(["schema.md"]);
|
||||
});
|
||||
|
||||
it("reports missing required folders and files without using product-specific branches", async () => {
|
||||
const root = await makeRoot();
|
||||
|
||||
const status = await inspectPluginLocalFolder({
|
||||
folderKey: "content-root",
|
||||
storedConfig: {
|
||||
path: root,
|
||||
requiredDirectories: ["sources"],
|
||||
requiredFiles: ["schema.md"],
|
||||
},
|
||||
});
|
||||
|
||||
expect(status.healthy).toBe(false);
|
||||
expect(status.missingDirectories).toEqual(["sources"]);
|
||||
expect(status.missingFiles).toEqual(["schema.md"]);
|
||||
expect(status.problems.map((item) => item.code)).toEqual(
|
||||
expect.arrayContaining(["missing_directory", "missing_file"]),
|
||||
);
|
||||
});
|
||||
|
||||
it("reports all required paths as missing when the configured root does not exist", async () => {
|
||||
const root = await makeRoot();
|
||||
const missingRoot = path.join(root, "missing-root");
|
||||
|
||||
const status = await inspectPluginLocalFolder({
|
||||
folderKey: "content-root",
|
||||
storedConfig: {
|
||||
path: missingRoot,
|
||||
requiredDirectories: ["sources"],
|
||||
requiredFiles: ["schema.md"],
|
||||
},
|
||||
});
|
||||
|
||||
expect(status.healthy).toBe(false);
|
||||
expect(status.configured).toBe(true);
|
||||
expect(status.readable).toBe(false);
|
||||
expect(status.missingDirectories).toEqual(["sources"]);
|
||||
expect(status.missingFiles).toEqual(["schema.md"]);
|
||||
expect(status.problems.map((item) => item.code)).toContain("missing");
|
||||
});
|
||||
|
||||
it("uses manifest declaration access and required paths over stored or caller overrides", async () => {
|
||||
const root = await makeRoot();
|
||||
await fs.mkdir(path.join(root, "manifest-dir"));
|
||||
await fs.writeFile(path.join(root, "manifest.md"), "schema", "utf8");
|
||||
|
||||
const status = await inspectPluginLocalFolder({
|
||||
folderKey: "content-root",
|
||||
declaration: {
|
||||
folderKey: "content-root",
|
||||
displayName: "Content root",
|
||||
access: "read",
|
||||
requiredDirectories: ["manifest-dir"],
|
||||
requiredFiles: ["manifest.md"],
|
||||
},
|
||||
storedConfig: {
|
||||
path: root,
|
||||
access: "readWrite",
|
||||
requiredDirectories: ["stored-dir"],
|
||||
requiredFiles: ["stored.md"],
|
||||
},
|
||||
overrideConfig: {
|
||||
access: "readWrite",
|
||||
requiredDirectories: ["override-dir"],
|
||||
requiredFiles: ["override.md"],
|
||||
},
|
||||
});
|
||||
|
||||
expect(status.access).toBe("read");
|
||||
expect(status.writable).toBe(false);
|
||||
expect(status.requiredDirectories).toEqual(["manifest-dir"]);
|
||||
expect(status.requiredFiles).toEqual(["manifest.md"]);
|
||||
expect(status.healthy).toBe(true);
|
||||
});
|
||||
|
||||
it("prepares required directories for a read-write folder without creating required files", async () => {
|
||||
const root = await makeRoot();
|
||||
|
||||
await preparePluginLocalFolder({
|
||||
folderKey: "content-root",
|
||||
storedConfig: {
|
||||
path: root,
|
||||
access: "readWrite",
|
||||
requiredDirectories: ["sources", "wiki/concepts"],
|
||||
requiredFiles: ["schema.md"],
|
||||
},
|
||||
});
|
||||
|
||||
await expect(fs.stat(path.join(root, "sources"))).resolves.toMatchObject({});
|
||||
await expect(fs.stat(path.join(root, "wiki/concepts"))).resolves.toMatchObject({});
|
||||
await expect(fs.stat(path.join(root, "schema.md"))).rejects.toMatchObject({ code: "ENOENT" });
|
||||
|
||||
const status = await inspectPluginLocalFolder({
|
||||
folderKey: "content-root",
|
||||
storedConfig: {
|
||||
path: root,
|
||||
access: "readWrite",
|
||||
requiredDirectories: ["sources", "wiki/concepts"],
|
||||
requiredFiles: ["schema.md"],
|
||||
},
|
||||
});
|
||||
expect(status.missingDirectories).toEqual([]);
|
||||
expect(status.missingFiles).toEqual(["schema.md"]);
|
||||
});
|
||||
|
||||
it("allows write access to repair folders that are only missing required paths", async () => {
|
||||
const root = await makeRoot();
|
||||
const status = await inspectPluginLocalFolder({
|
||||
folderKey: "content-root",
|
||||
storedConfig: {
|
||||
path: root,
|
||||
access: "readWrite",
|
||||
requiredFiles: ["schema.md"],
|
||||
},
|
||||
});
|
||||
|
||||
expect(status.healthy).toBe(false);
|
||||
expect(() => assertConfiguredLocalFolder(status)).toThrow("Local folder is not healthy");
|
||||
expect(() => assertWritableConfiguredLocalFolder(status)).not.toThrow();
|
||||
|
||||
await writePluginLocalFolderTextAtomic(root, "schema.md", "schema");
|
||||
const repaired = await inspectPluginLocalFolder({
|
||||
folderKey: "content-root",
|
||||
storedConfig: {
|
||||
path: root,
|
||||
access: "readWrite",
|
||||
requiredFiles: ["schema.md"],
|
||||
},
|
||||
});
|
||||
expect(repaired.healthy).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects traversal outside the configured folder", async () => {
|
||||
const root = await makeRoot();
|
||||
|
||||
await expect(resolvePluginLocalFolderPath(root, "../outside.txt")).rejects.toMatchObject({
|
||||
status: 403,
|
||||
});
|
||||
});
|
||||
|
||||
it("detects required symlinks that escape the configured folder", async () => {
|
||||
const root = await makeRoot();
|
||||
const outside = await makeRoot();
|
||||
await fs.writeFile(path.join(outside, "secret.txt"), "nope", "utf8");
|
||||
await fs.symlink(path.join(outside, "secret.txt"), path.join(root, "linked.txt"));
|
||||
|
||||
const status = await inspectPluginLocalFolder({
|
||||
folderKey: "content-root",
|
||||
storedConfig: {
|
||||
path: root,
|
||||
requiredFiles: ["linked.txt"],
|
||||
},
|
||||
});
|
||||
|
||||
expect(status.healthy).toBe(false);
|
||||
expect(status.problems.some((item) => item.code === "symlink_escape")).toBe(true);
|
||||
});
|
||||
|
||||
it("writes files atomically under the root and can read them back", async () => {
|
||||
const root = await makeRoot();
|
||||
await fs.mkdir(path.join(root, "nested"));
|
||||
|
||||
await writePluginLocalFolderTextAtomic(root, "nested/page.md", "hello");
|
||||
await writePluginLocalFolderTextAtomic(root, "nested/page.md", "updated");
|
||||
|
||||
await expect(readPluginLocalFolderText(root, "nested/page.md")).resolves.toBe("updated");
|
||||
const leftovers = await fs.readdir(path.join(root, "nested"));
|
||||
expect(leftovers.filter((name) => name.includes(".paperclip-"))).toEqual([]);
|
||||
});
|
||||
|
||||
it("lists nested local folder entries without following symlink escapes", async () => {
|
||||
const root = await makeRoot();
|
||||
const outside = await makeRoot();
|
||||
await fs.mkdir(path.join(root, "wiki/concepts"), { recursive: true });
|
||||
await fs.writeFile(path.join(root, "wiki/concepts/live.md"), "# Live\n", "utf8");
|
||||
await fs.writeFile(path.join(outside, "secret.md"), "# Secret\n", "utf8");
|
||||
await fs.symlink(outside, path.join(root, "wiki/outside"));
|
||||
|
||||
const listing = await listPluginLocalFolderEntries(root, {
|
||||
relativePath: "wiki",
|
||||
recursive: true,
|
||||
maxEntries: 20,
|
||||
});
|
||||
|
||||
expect(listing.entries.map((entry) => entry.path)).toContain("wiki/concepts/live.md");
|
||||
expect(listing.entries.map((entry) => entry.path)).not.toContain("wiki/outside/secret.md");
|
||||
expect(listing.truncated).toBe(false);
|
||||
});
|
||||
|
||||
it("revalidates temp-file containment before writing atomic contents", async () => {
|
||||
const root = await makeRoot();
|
||||
const outside = await makeRoot();
|
||||
const nested = path.join(root, "nested");
|
||||
await fs.mkdir(nested);
|
||||
const originalOpen = fs.open.bind(fs);
|
||||
const openSpy = vi.spyOn(fs, "open");
|
||||
openSpy.mockImplementationOnce(async (file, flags, mode) => {
|
||||
await fs.rm(nested, { recursive: true, force: true });
|
||||
await fs.symlink(outside, nested);
|
||||
return originalOpen(file, flags, mode);
|
||||
});
|
||||
|
||||
try {
|
||||
await expect(writePluginLocalFolderTextAtomic(root, "nested/page.md", "secret")).rejects.toMatchObject({
|
||||
status: 403,
|
||||
});
|
||||
await expect(fs.readFile(path.join(outside, "page.md"), "utf8")).rejects.toMatchObject({ code: "ENOENT" });
|
||||
expect(await fs.readdir(outside)).toEqual([]);
|
||||
} finally {
|
||||
openSpy.mockRestore();
|
||||
}
|
||||
});
|
||||
});
|
||||
Loading…
Add table
Add a link
Reference in a new issue