@checkstack/backend 0.8.2 → 0.9.0

package/src/services/plugin-manager-router.ts

@@ -0,0 +1,219 @@
+import { implement, ORPCError } from "@orpc/server";
+import { desc } from "drizzle-orm";
+import {
+  autoAuthMiddleware,
+  coreServices,
+  type RpcContext,
+  type SafeDatabase,
+} from "@checkstack/backend-api";
+import {
+  pluginManagerContract,
+  type InstalledPlugin,
+} from "@checkstack/pluginmanager-common";
+import {
+  pluginPackageTypeSchema,
+  pluginSourceSchema,
+} from "@checkstack/common";
+import type { PluginManager } from "../plugin-manager";
+import type { ServiceRegistry } from "./service-registry";
+import type { PluginEventRecorder } from "./plugin-event-recorder";
+import { plugins } from "../schema";
+import {
+  installOriginator,
+  previewInstallOriginator,
+  previewUninstallOriginator,
+  uninstallOriginator,
+} from "./plugin-manager-orchestrator";
+import {
+  PluginInstallError,
+  type PluginInstallErrorCode,
+} from "./plugin-installers/plugin-install-error";
+
+/**
+ * Map our installer/orchestrator error codes onto the closest oRPC error
+ * codes so the UI sees a meaningful HTTP status + message instead of a
+ * generic `INTERNAL_SERVER_ERROR`.
+ *
+ * oRPC's built-in `ORPCError` codes match common HTTP semantics; we route
+ * `COMPATIBILITY_FAILED` and `VALIDATION_FAILED` to `BAD_REQUEST` because
+ * neither is a server fault — both indicate user-correctable input.
+ */
+const ORPC_CODE_MAP: Record<
+  PluginInstallErrorCode,
+  | "BAD_REQUEST"
+  | "UNAUTHORIZED"
+  | "FORBIDDEN"
+  | "NOT_FOUND"
+  | "PAYLOAD_TOO_LARGE"
+  | "BAD_GATEWAY"
+  | "NOT_IMPLEMENTED"
+> = {
+  NOT_FOUND: "NOT_FOUND",
+  BAD_REQUEST: "BAD_REQUEST",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  FORBIDDEN: "FORBIDDEN",
+  PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
+  BAD_GATEWAY: "BAD_GATEWAY",
+  VALIDATION_FAILED: "BAD_REQUEST",
+  COMPATIBILITY_FAILED: "BAD_REQUEST",
+  NOT_IMPLEMENTED: "NOT_IMPLEMENTED",
+};
+
+/**
+ * Run an originator function and translate any `PluginInstallError` into
+ * an `ORPCError` with the right code + the user-facing message intact.
+ * Other errors propagate untouched and surface as 500s — those represent
+ * genuine bugs and stay loud.
+ */
+async function withTranslatedErrors<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof PluginInstallError) {
+      const data: Record<string, unknown> = { kind: error.code };
+      if (error.details) Object.assign(data, error.details);
+      throw new ORPCError(ORPC_CODE_MAP[error.code], {
+        message: error.message,
+        data,
+      });
+    }
+    throw error;
+  }
+}
+
+/**
+ * oRPC router that backs `pluginManagerContract`.
+ *
+ * Lives in `core/backend` because it directly references the in-process
+ * `PluginManager` instance. Wired into the request pipeline via
+ * `pluginManager.registerCoreRouter("pluginmanager", ...)`.
+ */
+export function createPluginManagerRouter({
+  db,
+  pluginManager,
+  registry,
+  eventRecorder,
+  workspaceRoot,
+  runtimeDir,
+}: {
+  db: SafeDatabase<Record<string, unknown>>;
+  pluginManager: PluginManager;
+  registry: ServiceRegistry;
+  eventRecorder: PluginEventRecorder;
+  workspaceRoot: string;
+  runtimeDir: string;
+}) {
+  // touch coreServices to keep the import alive in case future router
+  // procedures need to resolve services on demand.
+  void coreServices;
+
+  const impl = implement(pluginManagerContract)
+    .$context<RpcContext>()
+    .use(autoAuthMiddleware);
+
+  return impl.router({
+    list: impl.list.handler(async () => {
+      const rows = await db
+        .select()
+        .from(plugins)
+        .orderBy(desc(plugins.id));
+      const list: InstalledPlugin[] = rows.map((row) => {
+        // type may legitimately not match the enum for legacy/tooling rows
+        // — fall back to a safe value rather than 500-ing on parse.
+        const typeParsed = pluginPackageTypeSchema.safeParse(row.type);
+        // metadata is JSONB; drizzle returns `unknown | null`. The contract
+        // declares it as `optional()` (accepts undefined, NOT null), so
+        // coerce. Also accept only objects — string/number/array would fail
+        // schema validation.
+        const metadata =
+          row.metadata && typeof row.metadata === "object" && !Array.isArray(row.metadata)
+            ? (row.metadata as InstalledPlugin["metadata"])
+            : undefined;
+        // source: null for monorepo-local; validated PluginSource for
+        // runtime-installed. Wrap parse in safeParse so a malformed
+        // legacy row doesn't break the whole list response.
+        const sourceParsed = row.source
+          ? pluginSourceSchema.safeParse(row.source)
+          : undefined;
+        return {
+          name: row.name,
+          version: row.version ?? "",
+          type: typeParsed.success ? typeParsed.data : "backend",
+          enabled: row.enabled,
+          isUninstallable: row.isUninstallable,
+          isPrimary: row.isPrimary,
+          bundleId: row.bundleId,
+          source: sourceParsed?.success ? sourceParsed.data : null,
+          metadata,
+        };
+      });
+      return { plugins: list };
+    }),
+
+    previewInstall: impl.previewInstall.handler(({ input }) =>
+      withTranslatedErrors(() =>
+        previewInstallOriginator({
+          source: input.source,
+          registry,
+          workspaceRoot,
+          runtimeDir,
+        }),
+      ),
+    ),
+
+    install: impl.install.handler(async ({ input, context }) => {
+      const userId = (context.user as { id?: string } | undefined)?.id;
+      const result = await withTranslatedErrors(() =>
+        installOriginator({
+          source: input.source,
+          pluginManager,
+          db,
+          registry,
+          workspaceRoot,
+          runtimeDir,
+          eventRecorder,
+          userId,
+        }),
+      );
+      return {
+        success: true,
+        bundleId: result.bundleId,
+        installedPackages: result.installedPackages,
+      };
+    }),
+
+    previewUninstall: impl.previewUninstall.handler(({ input }) =>
+      withTranslatedErrors(() =>
+        previewUninstallOriginator({
+          pluginName: input.pluginName,
+          db,
+        }),
+      ),
+    ),
+
+    uninstall: impl.uninstall.handler(async ({ input, context }) => {
+      const userId = (context.user as { id?: string } | undefined)?.id;
+      const result = await withTranslatedErrors(() =>
+        uninstallOriginator({
+          pluginName: input.pluginName,
+          deleteSchema: input.deleteSchema,
+          deleteConfigs: input.deleteConfigs,
+          cascade: input.cascade,
+          pluginManager,
+          db,
+          eventRecorder,
+          userId,
+        }),
+      );
+      return { success: true, uninstalledPackages: result.uninstalledPackages };
+    }),
+
+    events: impl.events.handler(async ({ input }) => {
+      const events = await eventRecorder.list({
+        pluginName: input.pluginName,
+        limit: input.limit,
+      });
+      return { events };
+    }),
+  });
+}

package/src/utils/plugin-discovery.test.ts

@@ -51,6 +51,7 @@ describe("extractPluginMetadata", () => {
       pluginPath: "/fake/path/test-backend",
       type: "backend",
       enabled: true,
+      version: "0.0.1",
     });
   });
 
@@ -288,6 +289,7 @@ describe("syncPluginsToDatabase", () => {
         pluginPath: "/workspace/plugins/new-backend",
         type: "backend",
         enabled: true,
+        version: "2.1.0",
       },
     ];
 
@@ -310,6 +312,7 @@ describe("syncPluginsToDatabase", () => {
       type: "backend",
       enabled: true,
       isUninstallable: false,
+      version: "2.1.0",
     });
   });
 
@@ -320,6 +323,7 @@ describe("syncPluginsToDatabase", () => {
         pluginPath: "/workspace/plugins/new-location",
         type: "backend",
         enabled: true,
+        version: "1.0.0",
       },
     ];
 
@@ -347,6 +351,7 @@ describe("syncPluginsToDatabase", () => {
     expect(updateCall.set).toHaveBeenCalledWith({
       path: "/workspace/plugins/new-location",
       type: "backend",
+      version: "1.0.0",
     });
   });
 
@@ -357,6 +362,7 @@ describe("syncPluginsToDatabase", () => {
         pluginPath: "/workspace/plugins/remote-backend",
         type: "backend",
         enabled: true,
+        version: "0.0.0",
       },
     ];
 

package/src/utils/plugin-discovery.ts

@@ -10,6 +10,7 @@ export interface PluginMetadata {
   pluginPath: string; // Absolute path to plugin directory
   type: "backend" | "frontend" | "common";
   enabled: boolean;
+  version: string; // From package.json "version"
 }
 
 /**
@@ -64,6 +65,7 @@ export function extractPluginMetadata({
       pluginPath: pluginDir,
       type,
       enabled: true, // Local plugins are always enabled
+      version: typeof pkgJson.version === "string" ? pkgJson.version : "",
     };
   } catch (error) {
     rootLogger.debug(`⚠️  Failed to read package.json for ${pluginDir}:`, error);
@@ -148,16 +150,19 @@ export async function syncPluginsToDatabase({
         type: plugin.type,
         enabled: plugin.enabled,
         isUninstallable: false, // Local plugins are part of monorepo
+        version: plugin.version,
       });
     } else {
       // Update existing plugin ONLY if it's a local plugin (not remotely installed)
-      // This handles the case where a plugin directory was renamed
+      // This handles the case where a plugin directory was renamed AND keeps
+      // `version` in lockstep with each release.
       if (!existing[0].isUninstallable) {
         await db
           .update(plugins)
           .set({
             path: plugin.pluginPath,
             type: plugin.type,
+            version: plugin.version,
           })
           .where(
             and(

package/tsconfig.json

@@ -22,6 +22,9 @@
     {
       "path": "../drizzle-helper"
     },
+    {
+      "path": "../pluginmanager-common"
+    },
     {
       "path": "../queue-api"
     },

package/src/plugin-lifecycle.test.ts

@@ -1,276 +0,0 @@
-import { describe, it, expect, mock, beforeEach, spyOn } from "bun:test";
-import {
-  createMockEventBus,
-  createMockPluginInstaller,
-  createMockQueueManager,
-  type MockEventBus,
-  type MockPluginInstaller,
-} from "@checkstack/test-utils-backend";
-import { coreServices, coreHooks } from "@checkstack/backend-api";
-
-// Note: ./db and ./logger are mocked via test-preload.ts (bunfig.toml preload)
-// This ensures mocks are in place BEFORE any module imports them
-
-import { PluginManager } from "./plugin-manager";
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Tests
-// ─────────────────────────────────────────────────────────────────────────────
-
-describe("Plugin Lifecycle", () => {
-  let pluginManager: PluginManager;
-  let mockEventBus: MockEventBus;
-  let mockInstaller: MockPluginInstaller;
-
-  beforeEach(() => {
-    pluginManager = new PluginManager();
-    mockEventBus = createMockEventBus();
-    mockInstaller = createMockPluginInstaller();
-
-    // Access internal registry to override factory (factories take precedence)
-    const registry = (pluginManager as never)["registry"] as {
-      registerFactory: <T>(ref: { id: string }, factory: () => T) => void;
-      register: <T>(ref: { id: string }, impl: T) => void;
-    };
-
-    // Override EventBus factory with our mock
-    registry.registerFactory(
-      coreServices.eventBus,
-      () => mockEventBus as never
-    );
-
-    // Register services
-    registry.register(coreServices.pluginInstaller, mockInstaller as never);
-    registry.register(
-      coreServices.queueManager,
-      createMockQueueManager() as never
-    );
-  });
-
-  describe("requestInstallation", () => {
-    it("should emit pluginInstallationRequested broadcast", async () => {
-      await pluginManager.requestInstallation("test-plugin", "/path/to/plugin");
-
-      expect(mockEventBus._emittedEvents).toContainEqual({
-        hook: coreHooks.pluginInstallationRequested.id,
-        payload: { pluginId: "test-plugin", pluginPath: "/path/to/plugin" },
-      });
-    });
-  });
-
-  describe("requestDeregistration", () => {
-    it("should emit pluginDeregistrationRequested broadcast", async () => {
-      await pluginManager.requestDeregistration("test-plugin", {
-        deleteSchema: false,
-      });
-
-      expect(mockEventBus._emittedEvents).toContainEqual({
-        hook: coreHooks.pluginDeregistrationRequested.id,
-        payload: { pluginId: "test-plugin", deleteSchema: false },
-      });
-    });
-
-    it("should include deleteSchema flag in broadcast", async () => {
-      await pluginManager.requestDeregistration("test-plugin", {
-        deleteSchema: true,
-      });
-
-      expect(mockEventBus._emittedEvents).toContainEqual({
-        hook: coreHooks.pluginDeregistrationRequested.id,
-        payload: { pluginId: "test-plugin", deleteSchema: true },
-      });
-    });
-  });
-
-  describe("setupLifecycleListeners", () => {
-    it("should register listeners for installation broadcasts", async () => {
-      await pluginManager.setupLifecycleListeners();
-
-      // Spy on loadSinglePlugin and make it a no-op to avoid actual import
-      const loadSpy = spyOn(
-        pluginManager,
-        "loadSinglePlugin"
-      ).mockImplementation(async () => {});
-      await mockEventBus._triggerBroadcast(
-        coreHooks.pluginInstallationRequested,
-        {
-          pluginId: "broadcast-plugin",
-          pluginPath: "/broadcast/path",
-        }
-      );
-
-      expect(loadSpy).toHaveBeenCalledWith(
-        "broadcast-plugin",
-        "/broadcast/path"
-      );
-    });
-
-    it("should register listeners for deregistration broadcasts", async () => {
-      await pluginManager.setupLifecycleListeners();
-
-      // Trigger a broadcast and verify the listener responds
-      const deregSpy = spyOn(pluginManager, "deregisterPlugin");
-      await mockEventBus._triggerBroadcast(
-        coreHooks.pluginDeregistrationRequested,
-        {
-          pluginId: "broadcast-plugin",
-          deleteSchema: true,
-        }
-      );
-
-      expect(deregSpy).toHaveBeenCalledWith("broadcast-plugin", {
-        deleteSchema: true,
-      });
-    });
-  });
-
-  describe("loadSinglePlugin", () => {
-    it("should emit pluginInstalling local hook", async () => {
-      // Try loading - will fail import but should still emit installing hook
-      try {
-        await pluginManager.loadSinglePlugin(
-          "nonexistent-plugin",
-          "/nonexistent/path"
-        );
-      } catch {
-        // Expected to fail since plugin doesn't exist
-      }
-
-      // Should have emitted pluginInstalling locally
-      expect(mockEventBus._localEmittedEvents).toContainEqual({
-        hook: coreHooks.pluginInstalling.id,
-        payload: { pluginId: "nonexistent-plugin" },
-      });
-    });
-
-    it("should call installer if import fails", async () => {
-      try {
-        await pluginManager.loadSinglePlugin(
-          "test-remote-plugin",
-          "/nonexistent/path"
-        );
-      } catch {
-        // Expected to fail at the final import, but installer should be called
-      }
-
-      // Installer should have been called when imports failed
-      expect(mockInstaller._installCalls).toContain("test-remote-plugin");
-    });
-  });
-
-  describe("deregisterPlugin", () => {
-    beforeEach(() => {
-      // Setup cleanup handlers for a plugin
-      const cleanupHandlers = (pluginManager as never)[
-        "cleanupHandlers"
-      ] as Map<string, (() => Promise<void>)[]>;
-      cleanupHandlers.set("test-plugin", [async () => {}]);
-    });
-
-    it("should emit pluginDeregistering local hook", async () => {
-      await pluginManager.deregisterPlugin("test-plugin", {
-        deleteSchema: false,
-      });
-
-      const deregisteringEvent = mockEventBus._localEmittedEvents.find(
-        (e) => e.hook === coreHooks.pluginDeregistering.id
-      );
-      expect(deregisteringEvent).toBeDefined();
-      expect(deregisteringEvent?.payload).toMatchObject({
-        pluginId: "test-plugin",
-      });
-    });
-
-    it("should emit pluginDeregistered after cleanup", async () => {
-      await pluginManager.deregisterPlugin("test-plugin", {
-        deleteSchema: false,
-      });
-
-      const deregisteredEvent = mockEventBus._emittedEvents.find(
-        (e) => e.hook === coreHooks.pluginDeregistered.id
-      );
-      expect(deregisteredEvent).toBeDefined();
-      expect(deregisteredEvent?.payload).toMatchObject({
-        pluginId: "test-plugin",
-      });
-    });
-
-    it("should run cleanup handlers in reverse order", async () => {
-      const callOrder: number[] = [];
-      const cleanupHandlers = (pluginManager as never)[
-        "cleanupHandlers"
-      ] as Map<string, (() => Promise<void>)[]>;
-
-      cleanupHandlers.set("test-plugin", [
-        async () => {
-          callOrder.push(1);
-        },
-        async () => {
-          callOrder.push(2);
-        },
-        async () => {
-          callOrder.push(3);
-        },
-      ]);
-
-      await pluginManager.deregisterPlugin("test-plugin", {
-        deleteSchema: false,
-      });
-
-      expect(callOrder).toEqual([3, 2, 1]);
-    });
-
-    it("should remove plugin router", async () => {
-      const pluginRpcRouters = (pluginManager as never)[
-        "pluginRpcRouters"
-      ] as Map<string, unknown>;
-      pluginRpcRouters.set("test-plugin", { mockRouter: true });
-
-      await pluginManager.deregisterPlugin("test-plugin", {
-        deleteSchema: false,
-      });
-
-      expect(pluginRpcRouters.has("test-plugin")).toBe(false);
-    });
-
-    it("should clear access rules for plugin", async () => {
-      const registeredAccessRules = (pluginManager as never)[
-        "registeredAccessRules"
-      ] as { pluginId: string; id: string }[];
-
-      // Clear existing access rules first
-      while (registeredAccessRules.length > 0) {
-        registeredAccessRules.pop();
-      }
-
-      // Add test access rules
-      registeredAccessRules.push(
-        { pluginId: "test-plugin", id: "test-plugin.perm1" },
-        { pluginId: "test-plugin", id: "test-plugin.perm2" },
-        { pluginId: "other-plugin", id: "other-plugin.perm1" }
-      );
-
-      await pluginManager.deregisterPlugin("test-plugin", {
-        deleteSchema: false,
-      });
-
-      // Use getAllAccessRules() which returns the current array
-      const remaining = pluginManager.getAllAccessRules();
-      expect(remaining).toHaveLength(1);
-      expect(remaining[0].id).toBe("other-plugin.perm1");
-    });
-  });
-
-  describe("registerCoreRouter", () => {
-    it("should add router to pluginRpcRouters", () => {
-      const mockRouter = { test: true };
-
-      pluginManager.registerCoreRouter("admin", mockRouter);
-
-      const pluginRpcRouters = (pluginManager as never)[
-        "pluginRpcRouters"
-      ] as Map<string, unknown>;
-      expect(pluginRpcRouters.get("admin")).toBe(mockRouter);
-    });
-  });
-});

package/src/plugin-manager/plugin-admin-router.ts

@@ -1,89 +0,0 @@
-import { implement } from "@orpc/server";
-import {
-  autoAuthMiddleware,
-  type RpcContext,
-} from "@checkstack/backend-api";
-import { pluginAdminContract } from "@checkstack/backend-api";
-import type { PluginManager } from "../plugin-manager";
-import type { PluginInstaller } from "@checkstack/backend-api";
-import { db } from "../db";
-import { plugins } from "../schema";
-import { eq } from "drizzle-orm";
-import { rootLogger } from "../logger";
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Router Factory
-// ─────────────────────────────────────────────────────────────────────────────
-
-export function createPluginAdminRouter({
-  pluginManager,
-  installer,
-}: {
-  pluginManager: PluginManager;
-  installer: PluginInstaller;
-}) {
-  const impl = implement(pluginAdminContract)
-    .$context<RpcContext>()
-    .use(autoAuthMiddleware);
-
-  return impl.router({
-    install: impl.install.handler(async ({ input }) => {
-      const { packageName } = input;
-      rootLogger.info(`📦 Installing plugin: ${packageName}`);
-
-      // 1. npm install to filesystem
-      const result = await installer.install(packageName);
-
-      // 2. Insert/update in DB with isUninstallable=true (remote plugin)
-      await db
-        .insert(plugins)
-        .values({
-          name: result.name,
-          path: result.path,
-          enabled: true,
-          isUninstallable: true, // Remote plugins can be uninstalled
-          type: "backend",
-        })
-        .onConflictDoUpdate({
-          target: [plugins.name],
-          set: { path: result.path, enabled: true },
-        });
-
-      // 3. Broadcast to all instances to load the plugin
-      await pluginManager.requestInstallation(result.name, result.path);
-
-      return {
-        success: true,
-        pluginId: result.name,
-        path: result.path,
-      };
-    }),
-
-    deregister: impl.deregister.handler(async ({ input }) => {
-      const { pluginId, deleteSchema } = input;
-      rootLogger.info(`🗑️ Deregistering plugin: ${pluginId}`);
-
-      // Check if plugin exists and is uninstallable
-      const existing = await db
-        .select()
-        .from(plugins)
-        .where(eq(plugins.name, pluginId))
-        .limit(1);
-
-      if (existing.length === 0) {
-        throw new Error(`Plugin ${pluginId} not found`);
-      }
-
-      if (!existing[0].isUninstallable) {
-        throw new Error(
-          `Plugin ${pluginId} is a core plugin and cannot be deregistered`
-        );
-      }
-
-      // Broadcast to all instances to deregister
-      await pluginManager.requestDeregistration(pluginId, { deleteSchema });
-
-      return { success: true };
-    }),
-  });
-}