Dotta
9c6f551595
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - The plugin system is the extension path for optional capabilities that should not require core product changes for every integration. > - Plugins need scoped host APIs for issue orchestration, documents, wakeups, summaries, activity attribution, and isolated database state. > - Without those host APIs, richer plugins either cannot coordinate Paperclip work safely or need privileged core-side special cases. > - This pull request adds the plugin orchestration host surface, scoped route dispatch, a database namespace layer, and a smoke plugin that exercises the contract. > - The benefit is a broader plugin API that remains company-scoped, auditable, and covered by tests. ## What Changed - Added plugin orchestration host APIs for issue creation, document access, wakeups, summaries, plugin-origin activity, and scoped API route dispatch. - Added plugin database namespace tables, schema exports, migration checks, and idempotent replay coverage under migration `0059_plugin_database_namespaces`. - Added shared plugin route/API types and validators used by server and SDK boundaries. - Expanded plugin SDK types, protocol helpers, worker RPC host behavior, and testing utilities for orchestration flows. - Added the `plugin-orchestration-smoke-example` package to exercise scoped routes, restricted database namespaces, issue orchestration, documents, wakeups, summaries, and UI status surfaces. - Kept the new orchestration smoke fixture out of the root pnpm workspace importer so this PR preserves the repository policy of not committing `pnpm-lock.yaml`. - Updated plugin docs and database docs for the new orchestration and database namespace surfaces. - Rebased the branch onto `public-gh/master`, resolved conflicts, and removed `pnpm-lock.yaml` from the final PR diff. ## Verification - `pnpm install --frozen-lockfile` - `pnpm --filter @paperclipai/db typecheck` - `pnpm exec vitest run packages/db/src/client.test.ts` - `pnpm exec vitest run server/src/__tests__/plugin-database.test.ts server/src/__tests__/plugin-orchestration-apis.test.ts server/src/__tests__/plugin-routes-authz.test.ts server/src/__tests__/plugin-scoped-api-routes.test.ts server/src/__tests__/plugin-sdk-orchestration-contract.test.ts` - From `packages/plugins/examples/plugin-orchestration-smoke-example`: `pnpm exec vitest run --config ./vitest.config.ts` - `pnpm --dir packages/plugins/examples/plugin-orchestration-smoke-example run typecheck` - `pnpm --filter @paperclipai/server typecheck` - PR CI on latest head `293fc67c`: `policy`, `verify`, `e2e`, and `security/snyk` all passed. ## Risks - Medium risk: this expands plugin host authority, so route auth, company scoping, and plugin-origin activity attribution need careful review. - Medium risk: database namespace migration behavior must remain idempotent for environments that may have seen earlier branch versions. - Medium risk: the orchestration smoke fixture is intentionally excluded from the root workspace importer to avoid a `pnpm-lock.yaml` PR diff; direct fixture verification remains listed above. - Low operational risk from the PR setup itself: the branch is rebased onto current `master`, the migration is ordered after upstream `0057`/`0058`, and `pnpm-lock.yaml` is not in the final diff. > 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`. Roadmap checked: this work aligns with the completed Plugin system milestone and extends the plugin surface rather than duplicating an unrelated planned core feature. ## Model Used - OpenAI Codex, GPT-5-based coding agent in a tool-enabled CLI environment. Exact hosted model build and context-window size are not exposed by the runtime; reasoning/tool use were enabled for repository inspection, editing, testing, git operations, and PR creation. ## 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 (N/A: no core UI screen change; example plugin UI contract is covered by tests) - [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>
76 lines
2.7 KiB
TypeScript
76 lines
2.7 KiB
TypeScript
import {
|
|
pgTable,
|
|
uuid,
|
|
text,
|
|
timestamp,
|
|
index,
|
|
uniqueIndex,
|
|
} from "drizzle-orm/pg-core";
|
|
import type {
|
|
PluginDatabaseMigrationStatus,
|
|
PluginDatabaseNamespaceMode,
|
|
PluginDatabaseNamespaceStatus,
|
|
} from "@paperclipai/shared";
|
|
import { plugins } from "./plugins.js";
|
|
|
|
/**
|
|
* Database namespace allocated to an installed plugin.
|
|
*
|
|
* Namespaces are deterministic and owned by the host. Plugin SQL may create
|
|
* objects only inside its namespace, while selected public core tables remain
|
|
* read-only join targets through runtime checks.
|
|
*/
|
|
export const pluginDatabaseNamespaces = pgTable(
|
|
"plugin_database_namespaces",
|
|
{
|
|
id: uuid("id").primaryKey().defaultRandom(),
|
|
pluginId: uuid("plugin_id")
|
|
.notNull()
|
|
.references(() => plugins.id, { onDelete: "cascade" }),
|
|
pluginKey: text("plugin_key").notNull(),
|
|
namespaceName: text("namespace_name").notNull(),
|
|
namespaceMode: text("namespace_mode").$type<PluginDatabaseNamespaceMode>().notNull().default("schema"),
|
|
status: text("status").$type<PluginDatabaseNamespaceStatus>().notNull().default("active"),
|
|
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
|
|
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
|
|
},
|
|
(table) => ({
|
|
pluginIdx: uniqueIndex("plugin_database_namespaces_plugin_idx").on(table.pluginId),
|
|
namespaceIdx: uniqueIndex("plugin_database_namespaces_namespace_idx").on(table.namespaceName),
|
|
statusIdx: index("plugin_database_namespaces_status_idx").on(table.status),
|
|
}),
|
|
);
|
|
|
|
/**
|
|
* Per-plugin migration ledger.
|
|
*
|
|
* Every migration file is recorded with a checksum. A previously applied
|
|
* migration whose checksum changes is rejected during later activation.
|
|
*/
|
|
export const pluginMigrations = pgTable(
|
|
"plugin_migrations",
|
|
{
|
|
id: uuid("id").primaryKey().defaultRandom(),
|
|
pluginId: uuid("plugin_id")
|
|
.notNull()
|
|
.references(() => plugins.id, { onDelete: "cascade" }),
|
|
pluginKey: text("plugin_key").notNull(),
|
|
namespaceName: text("namespace_name").notNull(),
|
|
migrationKey: text("migration_key").notNull(),
|
|
checksum: text("checksum").notNull(),
|
|
pluginVersion: text("plugin_version").notNull(),
|
|
status: text("status").$type<PluginDatabaseMigrationStatus>().notNull(),
|
|
startedAt: timestamp("started_at", { withTimezone: true }).notNull().defaultNow(),
|
|
appliedAt: timestamp("applied_at", { withTimezone: true }),
|
|
errorMessage: text("error_message"),
|
|
},
|
|
(table) => ({
|
|
pluginMigrationIdx: uniqueIndex("plugin_migrations_plugin_key_idx").on(
|
|
table.pluginId,
|
|
table.migrationKey,
|
|
),
|
|
pluginIdx: index("plugin_migrations_plugin_idx").on(table.pluginId),
|
|
statusIdx: index("plugin_migrations_status_idx").on(table.status),
|
|
}),
|
|
);
|