@checkstack/backend 0.0.2

package/src/integration/event-bus.integration.test.ts

@@ -0,0 +1,313 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { EventBus } from "../services/event-bus";
+import { createHook } from "@checkstack/backend-api";
+import {
+  createMockLogger,
+  createMockQueueManager,
+} from "@checkstack/test-utils-backend";
+import type { Logger } from "@checkstack/backend-api";
+import type { QueueManager } from "@checkstack/queue-api";
+
+describe("EventBus Integration Tests", () => {
+  let eventBus: EventBus;
+  let mockQueueManager: QueueManager;
+  let mockLogger: Logger;
+
+  beforeEach(() => {
+    mockQueueManager = createMockQueueManager();
+    mockLogger = createMockLogger();
+    eventBus = new EventBus(mockQueueManager, mockLogger);
+  });
+
+  describe("Permission Sync Scenario", () => {
+    it("should sync permissions across plugins using work-queue mode", async () => {
+      // Simulate the permissionsRegistered hook
+      const permissionsRegistered = createHook<{
+        pluginId: string;
+        permissions: Array<{ id: string; description?: string }>;
+      }>("core.permissionsRegistered");
+
+      const syncedPermissions: Array<{ id: string; description?: string }> = [];
+
+      // Auth-backend subscribes to sync permissions (work-queue mode)
+      await eventBus.subscribe(
+        "auth-backend",
+        permissionsRegistered,
+        async ({ permissions }) => {
+          // Simulate DB sync
+          syncedPermissions.push(...permissions);
+        },
+        {
+          mode: "work-queue",
+          workerGroup: "permission-db-sync",
+          maxRetries: 3,
+        }
+      );
+
+      // Emit permission registration events from different plugins
+      await eventBus.emit(permissionsRegistered, {
+        pluginId: "catalog",
+        permissions: [
+          { id: "catalog-backend.read", description: "Read catalog" },
+          { id: "catalog-backend.manage", description: "Manage catalog" },
+        ],
+      });
+
+      await eventBus.emit(permissionsRegistered, {
+        pluginId: "queue",
+        permissions: [
+          { id: "queue-backend.read", description: "Read queue" },
+          { id: "queue-backend.manage", description: "Manage queue" },
+        ],
+      });
+
+      // Wait for async processing
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // All permissions should be synced
+      expect(syncedPermissions.length).toBe(4);
+      expect(syncedPermissions.map((p) => p.id)).toContain(
+        "catalog-backend.read"
+      );
+      expect(syncedPermissions.map((p) => p.id)).toContain(
+        "catalog-backend.manage"
+      );
+      expect(syncedPermissions.map((p) => p.id)).toContain(
+        "queue-backend.read"
+      );
+      expect(syncedPermissions.map((p) => p.id)).toContain(
+        "queue-backend.manage"
+      );
+    });
+
+    it("should distribute jobs across instances in work-queue mode", async () => {
+      const testHook = createHook<{ data: string }>("test.hook");
+
+      let instance1Count = 0;
+      let instance2Count = 0;
+
+      // Simulate two different backend instances (different plugin IDs)
+      // Both use same workerGroup name but get namespaced differently
+      await eventBus.subscribe(
+        "plugin-instance-1",
+        testHook,
+        async () => {
+          instance1Count++;
+        },
+        {
+          mode: "work-queue",
+          workerGroup: "sync",
+        }
+      );
+
+      await eventBus.subscribe(
+        "plugin-instance-2",
+        testHook,
+        async () => {
+          instance2Count++;
+        },
+        {
+          mode: "work-queue",
+          workerGroup: "sync",
+        }
+      );
+
+      // Emit multiple events
+      await eventBus.emit(testHook, { data: "test1" });
+      await eventBus.emit(testHook, { data: "test2" });
+      await eventBus.emit(testHook, { data: "test3" });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Both instances should process jobs (different namespaces due to different plugin IDs)
+      const total = instance1Count + instance2Count;
+      expect(total).toBe(6); // Each instance gets all 3 jobs (different namespaces)
+
+      // Each instance should have processed the jobs
+      expect(instance1Count).toBe(3);
+      expect(instance2Count).toBe(3);
+    });
+  });
+
+  describe("Broadcast Scenario", () => {
+    it("should notify all plugin instances in broadcast mode", async () => {
+      const configUpdated = createHook<{ key: string; value: string }>(
+        "core.configUpdated"
+      );
+
+      const plugin1Notifications: string[] = [];
+      const plugin2Notifications: string[] = [];
+
+      // Multiple plugins subscribe to config updates
+      await eventBus.subscribe("plugin-1", configUpdated, async ({ key }) => {
+        plugin1Notifications.push(key);
+      });
+
+      await eventBus.subscribe("plugin-2", configUpdated, async ({ key }) => {
+        plugin2Notifications.push(key);
+      });
+
+      // Emit config update
+      await eventBus.emit(configUpdated, {
+        key: "database.url",
+        value: "postgresql://localhost",
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      // Both plugins should receive the notification
+      expect(plugin1Notifications).toContain("database.url");
+      expect(plugin2Notifications).toContain("database.url");
+    });
+  });
+
+  describe("Mixed Mode Scenario", () => {
+    it("should handle both broadcast and work-queue for same hook", async () => {
+      const dataProcessed = createHook<{ id: string }>("data.processed");
+
+      const broadcastNotifications: string[] = [];
+      const workQueueProcessed: string[] = [];
+
+      // Broadcast subscriber (logging/monitoring)
+      await eventBus.subscribe(
+        "logger-plugin",
+        dataProcessed,
+        async ({ id }) => {
+          broadcastNotifications.push(`logged-${id}`);
+        }
+      );
+
+      // Work-queue subscribers (actual processing - only one should handle)
+      await eventBus.subscribe(
+        "processor-plugin",
+        dataProcessed,
+        async ({ id }) => {
+          workQueueProcessed.push(`processed-${id}`);
+        },
+        {
+          mode: "work-queue",
+          workerGroup: "processor",
+        }
+      );
+
+      // Different work-queue subscriber with different group
+      await eventBus.subscribe(
+        "archiver-plugin",
+        dataProcessed,
+        async ({ id }) => {
+          workQueueProcessed.push(`archived-${id}`);
+        },
+        {
+          mode: "work-queue",
+          workerGroup: "archiver",
+        }
+      );
+
+      // Emit event
+      await eventBus.emit(dataProcessed, { id: "data-123" });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Broadcast should always receive
+      expect(broadcastNotifications).toContain("logged-data-123");
+
+      // Work-queue should process (both groups should handle it)
+      expect(workQueueProcessed).toContain("processed-data-123");
+      expect(workQueueProcessed).toContain("archived-data-123");
+      expect(workQueueProcessed.length).toBe(2);
+    });
+  });
+
+  describe("Error Resilience", () => {
+    it("should continue processing other listeners if one fails", async () => {
+      const testHook = createHook<{ value: number }>("test.hook");
+
+      const successful: number[] = [];
+
+      // First listener fails
+      await eventBus.subscribe("plugin-1", testHook, async () => {
+        throw new Error("Simulated failure");
+      });
+
+      // Second listener succeeds
+      await eventBus.subscribe("plugin-2", testHook, async ({ value }) => {
+        successful.push(value);
+      });
+
+      // Third listener succeeds
+      await eventBus.subscribe("plugin-3", testHook, async ({ value }) => {
+        successful.push(value * 2);
+      });
+
+      await eventBus.emit(testHook, { value: 10 });
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Despite first listener failing, others should succeed
+      expect(successful).toContain(10);
+      expect(successful).toContain(20);
+      expect(mockLogger.error).toHaveBeenCalled();
+    });
+  });
+
+  describe("Lifecycle", () => {
+    it("should properly clean up on shutdown", async () => {
+      const hook1 = createHook<{ test: string }>("hook1");
+      const hook2 = createHook<{ test: string }>("hook2");
+
+      await eventBus.subscribe("test-plugin", hook1, async () => {});
+      await eventBus.subscribe("test-plugin", hook2, async () => {});
+
+      await eventBus.shutdown();
+
+      // Should log shutdown
+      expect(mockLogger.info).toHaveBeenCalledWith("EventBus shut down");
+    });
+
+    it("should allow unsubscribe and re-subscribe with same workerGroup", async () => {
+      const testHook = createHook<{ value: number }>("test.hook");
+      const values: number[] = [];
+
+      // Subscribe
+      const unsub = await eventBus.subscribe(
+        "test-plugin",
+        testHook,
+        async ({ value }) => {
+          values.push(value);
+        },
+        {
+          mode: "work-queue",
+          workerGroup: "processor",
+        }
+      );
+
+      await eventBus.emit(testHook, { value: 1 });
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      expect(values).toContain(1);
+
+      // Unsubscribe
+      await unsub();
+
+      // Re-subscribe with same workerGroup (should work)
+      await eventBus.subscribe(
+        "test-plugin",
+        testHook,
+        async ({ value }) => {
+          values.push(value * 10);
+        },
+        {
+          mode: "work-queue",
+          workerGroup: "processor", // Same name OK after unsubscribe
+        }
+      );
+
+      await eventBus.emit(testHook, { value: 2 });
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      // First value from first subscription, second value from second subscription
+      expect(values).toContain(1);
+      expect(values).toContain(20); // 2 * 10
+    });
+  });
+});

package/src/logger.ts

@@ -0,0 +1,65 @@
+import { createLogger, format, transports } from "winston";
+import path from "node:path";
+import fs from "node:fs";
+
+const { combine, timestamp, printf, colorize, json } = format;
+
+const devFormat = printf(({ level, message, timestamp, ...meta }) => {
+  const plugin = meta.plugin ? `[${meta.plugin}] ` : "";
+  // Stringify rest of meta if it exists and isn't just plugin
+  const { plugin: _p, ...rest } = meta;
+  const metaStr = Object.keys(rest).length > 0 ? JSON.stringify(rest) : "";
+
+  return `${timestamp} ${level}: ${plugin}${message} ${metaStr}`;
+});
+
+// Plain text format for file logging (without colors)
+const fileFormat = printf(({ level, message, timestamp, ...meta }) => {
+  const plugin = meta.plugin ? `[${meta.plugin}] ` : "";
+  const { plugin: _p, ...rest } = meta;
+  const metaStr = Object.keys(rest).length > 0 ? JSON.stringify(rest) : "";
+
+  return `${timestamp} ${level}: ${plugin}${message} ${metaStr}`;
+});
+
+// Setup file transports for development
+const developmentTransports: transports.StreamTransportInstance[] = [
+  new transports.Console(),
+];
+
+if (process.env.NODE_ENV !== "production") {
+  // Create logs directory if it doesn't exist
+  const logsDir = path.join(process.cwd(), ".dev", "logs");
+  if (!fs.existsSync(logsDir)) {
+    fs.mkdirSync(logsDir, { recursive: true });
+  }
+
+  // Add file transports
+  developmentTransports.push(
+    // Timestamped log file
+    new transports.File({
+      filename: path.join(
+        logsDir,
+        `backend-${
+          new Date().toISOString().replaceAll(":", "-").split(".")[0]
+        }.log`
+      ),
+      format: combine(timestamp({ format: "YYYY-MM-DD HH:mm:ss" }), fileFormat),
+    }),
+    // Latest log file (always overwritten)
+    new transports.File({
+      filename: path.join(logsDir, "latest.log"),
+      format: combine(timestamp({ format: "YYYY-MM-DD HH:mm:ss" }), fileFormat),
+      options: { flags: "w" }, // Overwrite on each start
+    })
+  );
+}
+
+export const rootLogger = createLogger({
+  level: process.env.LOG_LEVEL || "info",
+  format:
+    process.env.NODE_ENV === "production"
+      ? json()
+      : combine(colorize(), timestamp({ format: "HH:mm:ss" }), devFormat),
+  transports: developmentTransports,
+});

package/src/openapi-router.ts

@@ -0,0 +1,177 @@
+/**
+ * OpenAPI Router - Exposes OpenAPI specification for external applications.
+ *
+ * This router provides a `/api/openapi.json` endpoint that returns the
+ * aggregated OpenAPI specification for all endpoints accessible by
+ * external applications (userType: "authenticated" | "public").
+ */
+import { OpenAPIGenerator } from "@orpc/openapi";
+import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
+import type { AnyContractRouter } from "@orpc/contract";
+import type { PluginManager } from "./plugin-manager";
+import type { AuthService } from "@checkstack/backend-api";
+
+/**
+ * Check if a user has a specific permission.
+ * Supports wildcard (*) for admin access.
+ */
+function hasPermission(
+  user: { permissions?: string[] },
+  permission: string
+): boolean {
+  if (!user.permissions) return false;
+  return (
+    user.permissions.includes("*") || user.permissions.includes(permission)
+  );
+}
+
+/**
+ * Extract procedure metadata from a contract using oRPC internal structure.
+ */
+function extractProcedureMetadata(
+  contract: unknown
+): { userType?: string; permissions?: string[] } | undefined {
+  const orpcData = (contract as Record<string, unknown>)?.["~orpc"] as
+    | { meta?: { userType?: string; permissions?: string[] } }
+    | undefined;
+  return orpcData?.meta;
+}
+
+/**
+ * Build a lookup map of operationId -> metadata from all contracts.
+ * operationId format: "pluginId.procedureName"
+ */
+function buildMetadataLookup(
+  contracts: Map<string, AnyContractRouter>
+): Map<string, { userType?: string; permissions?: string[] }> {
+  const lookup = new Map<
+    string,
+    { userType?: string; permissions?: string[] }
+  >();
+
+  for (const [pluginId, contract] of contracts) {
+    // Contract is an object with procedure names as keys
+    for (const [procedureName, procedure] of Object.entries(
+      contract as Record<string, unknown>
+    )) {
+      const meta = extractProcedureMetadata(procedure);
+      if (meta) {
+        const operationId = `${pluginId}.${procedureName}`;
+        lookup.set(operationId, meta);
+      }
+    }
+  }
+
+  return lookup;
+}
+
+/**
+ * Generate OpenAPI specification from registered plugin contracts.
+ * Returns all endpoints with their userType metadata visible as x-orpc-meta.
+ */
+export async function generateOpenApiSpec({
+  pluginManager,
+  baseUrl,
+}: {
+  pluginManager: PluginManager;
+  baseUrl: string;
+}): Promise<Record<string, unknown>> {
+  const contracts = pluginManager.getAllContracts();
+
+  // Build aggregated contract object: { pluginId: contract, ... }
+  const aggregatedContract: Record<string, AnyContractRouter> = {};
+  for (const [pluginId, contract] of contracts) {
+    aggregatedContract[pluginId] = contract;
+  }
+
+  // Build metadata lookup from contracts
+  const metadataLookup = buildMetadataLookup(contracts);
+
+  // Create OpenAPI generator with Zod v4 converter
+  const generator = new OpenAPIGenerator({
+    schemaConverters: [new ZodToJsonSchemaConverter()],
+  });
+
+  // Generate spec for all endpoints
+  const spec = (await generator.generate(aggregatedContract, {
+    info: {
+      title: "Checkstack API",
+      version: "1.0.0",
+      description: "API documentation for Checkstack platform endpoints.",
+    },
+    servers: [{ url: baseUrl }],
+  })) as {
+    paths?: Record<
+      string,
+      Record<string, { operationId?: string; "x-orpc-meta"?: unknown }>
+    >;
+  };
+
+  // Post-process: Add x-orpc-meta to each operation and prefix paths with /api
+  if (spec.paths) {
+    const prefixedPaths: typeof spec.paths = {};
+
+    for (const [path, methods] of Object.entries(spec.paths)) {
+      // Prefix path with /api
+      const prefixedPath = `/api${path.startsWith("/") ? path : `/${path}`}`;
+      prefixedPaths[prefixedPath] = methods;
+
+      // Add metadata to each operation
+      for (const operation of Object.values(methods)) {
+        if (operation.operationId) {
+          const meta = metadataLookup.get(operation.operationId);
+          if (meta) {
+            operation["x-orpc-meta"] = meta;
+          }
+        }
+      }
+    }
+
+    spec.paths = prefixedPaths;
+  }
+
+  return spec as Record<string, unknown>;
+}
+
+/**
+ * Create the OpenAPI endpoint handler for Hono.
+ * Returns a fetch handler that serves the OpenAPI spec.
+ */
+export function createOpenApiHandler({
+  pluginManager,
+  authService,
+  baseUrl,
+  requiredPermission,
+}: {
+  pluginManager: PluginManager;
+  authService: AuthService;
+  baseUrl: string;
+  requiredPermission: string;
+}): (req: Request) => Promise<Response> {
+  return async (req: Request) => {
+    // Authenticate request
+    const user = await authService.authenticate(req);
+
+    if (!user) {
+      return Response.json({ error: "Unauthorized" }, { status: 401 });
+    }
+
+    // Check permission (applications.manage from auth plugin)
+    // Services don't have permissions, so deny them access to docs
+    if (user.type === "service" || !hasPermission(user, requiredPermission)) {
+      return Response.json({ error: "Forbidden" }, { status: 403 });
+    }
+
+    try {
+      const spec = await generateOpenApiSpec({ pluginManager, baseUrl });
+
+      return Response.json(spec);
+    } catch (error) {
+      console.error("Failed to generate OpenAPI spec:", error);
+      return Response.json(
+        { error: "Failed to generate OpenAPI specification" },
+        { status: 500 }
+      );
+    }
+  };
+}