@checkstack/backend 0.8.1 → 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/services/readiness-registry.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, mock } from "bun:test";
+import {
+  CoreReadinessRegistry,
+  createScopedReadinessRegistry,
+} from "./readiness-registry";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+const mockLogger = createMockLogger();
+mock.module("../logger", () => ({
+  rootLogger: mockLogger,
+}));
+
+describe("CoreReadinessRegistry", () => {
+  let registry: CoreReadinessRegistry;
+
+  beforeEach(() => {
+    registry = new CoreReadinessRegistry();
+  });
+
+  it("starts empty", () => {
+    expect(registry.isEmpty()).toBe(true);
+  });
+
+  it("evaluates to ready=true with no probes", async () => {
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.checks).toHaveLength(0);
+  });
+
+  it("aggregates passing probes", async () => {
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: true }),
+    });
+    registry.register({
+      name: "queue",
+      check: async () => ({ ok: true }),
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(true);
+    expect(snapshot.checks).toHaveLength(2);
+    expect(snapshot.checks.every((c) => c.ok)).toBe(true);
+  });
+
+  it("ready=false when a critical probe fails", async () => {
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: false, message: "down" }),
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(false);
+    expect(snapshot.checks[0].message).toBe("down");
+  });
+
+  it("ready=true when only a non-critical probe fails", async () => {
+    registry.register({
+      name: "warmup",
+      critical: false,
+      check: async () => ({ ok: false }),
+    });
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: true }),
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(true);
+  });
+
+  it("treats thrown probes as failed and surfaces the error", async () => {
+    registry.register({
+      name: "boom",
+      check: async () => {
+        throw new Error("kaboom");
+      },
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.ready).toBe(false);
+    expect(snapshot.checks[0].ok).toBe(false);
+    expect(snapshot.checks[0].error).toBe("kaboom");
+  });
+
+  it("overwrites duplicate names with a warning", async () => {
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: false }),
+    });
+    registry.register({
+      name: "db",
+      check: async () => ({ ok: true }),
+    });
+    const snapshot = await registry.evaluate();
+    expect(snapshot.checks).toHaveLength(1);
+    expect(snapshot.checks[0].ok).toBe(true);
+  });
+
+  it("runs probes in parallel (total time ~ slowest probe)", async () => {
+    const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+    registry.register({
+      name: "slow-1",
+      check: async () => {
+        await delay(50);
+        return { ok: true };
+      },
+    });
+    registry.register({
+      name: "slow-2",
+      check: async () => {
+        await delay(50);
+        return { ok: true };
+      },
+    });
+    const start = Date.now();
+    await registry.evaluate();
+    const elapsed = Date.now() - start;
+    // Sequential would be ~100ms; parallel should be ~50ms.
+    expect(elapsed).toBeLessThan(95);
+  });
+
+  it("scoped registry forwards register() to the global", () => {
+    const scoped = createScopedReadinessRegistry(registry);
+    scoped.register({ name: "x", check: async () => ({ ok: true }) });
+    expect(registry.isEmpty()).toBe(false);
+  });
+});

package/src/services/readiness-registry.ts

@@ -0,0 +1,103 @@
+import type {
+  ReadinessCheck,
+  ReadinessCheckResult,
+  ReadinessRegistry,
+} from "@checkstack/backend-api";
+import { extractErrorMessage } from "@checkstack/common";
+import { rootLogger } from "../logger";
+
+/**
+ * Snapshot returned to /ready callers.
+ */
+export interface ReadinessSnapshot {
+  ready: boolean;
+  checks: Array<{
+    name: string;
+    critical: boolean;
+    ok: boolean;
+    message?: string;
+    /** Set when the probe threw (treated as ok=false for critical checks). */
+    error?: string;
+    /** Wall-clock duration for the probe (milliseconds). */
+    durationMs: number;
+  }>;
+}
+
+/**
+ * Core implementation backing both `coreServices.readinessRegistry` (plugin-facing)
+ * and the `/ready` endpoint (server-facing). Plugins call `register`; the server
+ * calls `evaluate()`.
+ */
+export class CoreReadinessRegistry {
+  private checks: ReadinessCheck[] = [];
+
+  register(check: ReadinessCheck): void {
+    if (this.checks.some((c) => c.name === check.name)) {
+      rootLogger.warn(
+        `ReadinessRegistry: probe '${check.name}' is already registered. Overwriting.`,
+      );
+      this.checks = this.checks.filter((c) => c.name !== check.name);
+    }
+    this.checks.push(check);
+    rootLogger.debug(
+      `   -> Registered readiness probe '${check.name}' (critical=${check.critical ?? true})`,
+    );
+  }
+
+  /**
+   * Run every probe in parallel. Critical failures set `ready = false`.
+   * Throws are caught and reported as `ok: false`.
+   */
+  async evaluate(): Promise<ReadinessSnapshot> {
+    const results = await Promise.all(
+      this.checks.map(async (c) => {
+        const start = performance.now();
+        const critical = c.critical ?? true;
+        try {
+          const r: ReadinessCheckResult = await c.check();
+          return {
+            name: c.name,
+            critical,
+            ok: r.ok,
+            message: r.message,
+            durationMs: Math.round(performance.now() - start),
+          };
+        } catch (error) {
+          return {
+            name: c.name,
+            critical,
+            ok: false,
+            error: extractErrorMessage(error, String(error)),
+            durationMs: Math.round(performance.now() - start),
+          };
+        }
+      }),
+    );
+
+    const ready = results.every((r) => r.ok || !r.critical);
+    return { ready, checks: results };
+  }
+
+  /**
+   * Returns true while no probes are registered. Used to give a stable answer
+   * before plugins have had a chance to register their checks.
+   */
+  isEmpty(): boolean {
+    return this.checks.length === 0;
+  }
+}
+
+/**
+ * Plugin-facing scoped view (currently identical to the underlying registry —
+ * we intentionally don't namespace probe names by plugin so operators can read
+ * them at a glance, but plugins are encouraged to prefix their own names).
+ */
+export function createScopedReadinessRegistry(
+  global: CoreReadinessRegistry,
+): ReadinessRegistry {
+  return {
+    register(check: ReadinessCheck) {
+      global.register(check);
+    },
+  };
+}

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

@@ -2,5 +2,40 @@
   "extends": "@checkstack/tsconfig/backend.json",
   "include": [
     "src"
+  ],
+  "references": [
+    {
+      "path": "../api-docs-common"
+    },
+    {
+      "path": "../auth-common"
+    },
+    {
+      "path": "../backend-api"
+    },
+    {
+      "path": "../cache-api"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../drizzle-helper"
+    },
+    {
+      "path": "../pluginmanager-common"
+    },
+    {
+      "path": "../queue-api"
+    },
+    {
+      "path": "../signal-backend"
+    },
+    {
+      "path": "../signal-common"
+    },
+    {
+      "path": "../test-utils-backend"
+    }
   ]
-}
+}