@checkstack/backend 0.8.2 → 0.9.1

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/services/queue-manager.ts

@@ -4,6 +4,9 @@ import type {
   SwitchResult,
   RecurringJobInfo,
   QueueStats,
+  JobSummary,
+  ListJobsOptions,
+  ListJobsResult,
 } from "@checkstack/queue-api";
 import type { QueuePluginRegistryImpl } from "./queue-plugin-registry";
 import type { Logger, ConfigService } from "@checkstack/backend-api";
@@ -276,7 +279,11 @@ export class QueueManagerImpl implements QueueManager {
   }
 
   async getAggregatedStats(): Promise<QueueStats> {
-    const aggregated: QueueStats = {
+    // The narrowest scope wins: if any queue reports `instance`, the
+    // aggregate cannot claim cluster-wide accuracy.
+    let scope: "instance" | "cluster" = "cluster";
+    let sawAny = false;
+    const aggregated: Omit<QueueStats, "scope"> = {
       pending: 0,
       processing: 0,
       completed: 0,
@@ -294,13 +301,81 @@ export class QueueManagerImpl implements QueueManager {
           aggregated.completed += stats.completed;
           aggregated.failed += stats.failed;
           aggregated.consumerGroups += stats.consumerGroups;
+          if (stats.scope === "instance") {
+            scope = "instance";
+          }
+          sawAny = true;
+        }
+      } catch {
+        // Queue may not be initialized yet
+      }
+    }
+
+    return { ...aggregated, scope: sawAny ? scope : "instance" };
+  }
+
+  /**
+   * Aggregate `listJobs` across every queue proxy. For deployments with a
+   * single queue (the common case) this is a straight pass-through; with
+   * multiple queues we over-fetch [0, offset+limit) per queue, merge-sort
+   * by the same key the per-queue impls use, then slice the requested
+   * window. Sort key:
+   *  - completed/failed → finishedAt desc (most-recent first)
+   *  - active           → startedAt asc (oldest still-running first)
+   *  - waiting/delayed  → enqueuedAt asc (FIFO)
+   */
+  async listJobs(opts: ListJobsOptions): Promise<ListJobsResult> {
+    const limit = Math.max(0, opts.limit);
+    const offset = Math.max(0, opts.offset);
+    if (limit === 0) {
+      return { items: [], total: 0, hasMore: false };
+    }
+
+    const fetchUpTo = offset + limit;
+    const merged: JobSummary[] = [];
+    let totalSum = 0;
+    let totalIsNull = false;
+
+    for (const proxy of this.queueProxies.values()) {
+      try {
+        const delegate = proxy.getDelegate();
+        if (delegate) {
+          const part = await delegate.listJobs({
+            state: opts.state,
+            offset: 0,
+            limit: fetchUpTo,
+          });
+          merged.push(...part.items);
+          if (part.total === null) {
+            totalIsNull = true;
+          } else {
+            totalSum += part.total;
+          }
         }
       } catch {
         // Queue may not be initialized yet
       }
     }
 
-    return aggregated;
+    const sortKey = (j: JobSummary): number => {
+      if (opts.state === "completed" || opts.state === "failed") {
+        return -(j.finishedAt?.getTime() ?? 0);
+      }
+      if (opts.state === "active") {
+        return j.startedAt?.getTime() ?? 0;
+      }
+      return j.enqueuedAt.getTime();
+    };
+    merged.sort((a, b) => sortKey(a) - sortKey(b));
+
+    const items = merged.slice(offset, offset + limit);
+    const total = totalIsNull ? null : totalSum;
+    const hasMore =
+      total === null
+        ? merged.length > offset + items.length
+        : offset + items.length < total;
+
+    return { items, total, hasMore };
   }
 
   async listAllRecurringJobs(): Promise<RecurringJobInfo[]> {

package/src/services/queue-proxy.ts

@@ -5,6 +5,8 @@ import type {
   QueueStats,
   RecurringJobDetails,
   RecurringSchedule,
+  ListJobsOptions,
+  ListJobsResult,
 } from "@checkstack/queue-api";
 import { rootLogger } from "../logger";
 
@@ -173,6 +175,11 @@ export class QueueProxy<T = unknown> implements Queue<T> {
     return delegate.getStats();
   }
 
+  async listJobs(opts: ListJobsOptions): Promise<ListJobsResult> {
+    const delegate = this.ensureDelegate();
+    return delegate.listJobs(opts);
+  }
+
   /**
    * Get subscription count (for testing/debugging)
    */

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"
     },