mirror of https://github.com/paperclipai/paperclip synced 2026-05-12 18:08:04 +02:00

Files

Dotta 3c73ed26b5 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>

2026-05-05 07:42:57 -05:00

scripts

Add plugin framework and settings UI

2026-03-13 16:22:34 -05:00

src

Expand plugin host surface (#5205 )

2026-05-05 07:42:57 -05:00

package.json

test: isolate CLI company import e2e state (#4560 )

2026-04-26 19:10:01 -07:00

README.md

Add plugin framework and settings UI

2026-03-13 16:22:34 -05:00

tsconfig.json

Add plugin framework and settings UI

2026-03-13 16:22:34 -05:00

README.md

File Browser Example Plugin

Example Paperclip plugin that demonstrates:

projectSidebarItem — An optional "Files" link under each project in the sidebar that opens the project detail with this plugin’s tab selected. This is controlled by plugin settings and defaults to off.
detailTab (entityType project) — A project detail tab with a workspace-path selector, a desktop two-column layout (file tree left, editor right), and a mobile one-panel flow with a back button from editor to file tree, including save support.

This is a repo-local example plugin for development. It should not be assumed to ship in a generic production build unless it is explicitly included.

Slots

Slot	Type	Description
Files (sidebar)	`projectSidebarItem`	Optional link under each project → project detail + tab.
Files (tab)	`detailTab`	Responsive tree/editor layout with save support.

Settings

Show Files in Sidebar — toggles the project sidebar link on or off. Defaults to off.
Comment File Links — controls whether comment annotations and the comment context-menu action are shown.

Capabilities

ui.sidebar.register — project sidebar item
ui.detailTab.register — project detail tab
projects.read — resolve project
project.workspaces.read — list workspaces and read paths for file access

Worker

getData workspaces — ctx.projects.listWorkspaces(projectId, companyId) (ordered, primary first).
getData fileList — { projectId, workspaceId, directoryPath? } → list directory entries for the workspace root or a subdirectory (Node fs).
getData fileContent — { projectId, workspaceId, filePath } → read file content using workspace-relative paths (Node fs).
performAction writeFile — { projectId, workspaceId, filePath, content } → write the current editor buffer back to disk.

Local Install (Dev)

From the repo root, build the plugin and install it by local path:

pnpm --filter @paperclipai/plugin-file-browser-example build
pnpm paperclipai plugin install ./packages/plugins/examples/plugin-file-browser-example

To uninstall:

pnpm paperclipai plugin uninstall paperclip-file-browser-example --force

Local development notes:

Build first. The host resolves the worker from the manifest entrypoints.worker (e.g. ./dist/worker.js). Run pnpm build in the plugin directory before installing so the worker file exists.
Dev-only install path. This local-path install flow assumes this monorepo checkout is present on disk. For deployed installs, publish an npm package instead of depending on packages/plugins/examples/... existing on the host.
Reinstall after pulling. If you installed a plugin by local path before the server stored package_path, the plugin may show status error (worker not found). Uninstall and install again so the server persists the path and can activate the plugin.
Optional: use paperclip-plugin-dev-server for UI hot-reload with devUiUrl in plugin config.

Structure

src/manifest.ts — manifest with projectSidebarItem and detailTab (entityTypes ["project"]).
src/worker.ts — data handlers for workspaces, file list, file content.
src/ui/index.tsx — FilesLink (sidebar) and FilesTab (workspace path selector + two-panel file tree/editor).

README.md Unescape Escape

File Browser Example Plugin

Slots

Settings

Capabilities

Worker

Local Install (Dev)

Structure

README.md