@checkstack/backend 0.0.2

package/src/services/queue-proxy.ts

@@ -0,0 +1,182 @@
+import type {
+  Queue,
+  QueueConsumer,
+  ConsumeOptions,
+  QueueStats,
+  RecurringJobDetails,
+} from "@checkstack/queue-api";
+import { rootLogger } from "../logger";
+
+/**
+ * Stored subscription for replay after backend switch
+ */
+interface StoredSubscription<T> {
+  consumer: QueueConsumer<T>;
+  options: ConsumeOptions;
+}
+
+/**
+ * QueueProxy wraps a real queue implementation and provides:
+ * - Stable reference that survives backend switches
+ * - Automatic subscription replay when backend changes
+ * - Pending operation tracking for graceful switching
+ */
+export class QueueProxy<T = unknown> implements Queue<T> {
+  private delegate: Queue<T> | undefined = undefined;
+  private subscriptions = new Map<string, StoredSubscription<T>>();
+  private pendingOperations: Promise<unknown>[] = [];
+  private stopped = false;
+
+  constructor(private readonly name: string) {}
+
+  /**
+   * Switch the underlying queue implementation.
+   * Called by QueueManager when backend changes.
+   */
+  async switchDelegate(newQueue: Queue<T>): Promise<void> {
+    rootLogger.debug(`Switching delegate for queue '${this.name}'`);
+
+    // Wait for pending operations to complete
+    if (this.pendingOperations.length > 0) {
+      rootLogger.debug(
+        `Waiting for ${this.pendingOperations.length} pending operations...`
+      );
+      await Promise.allSettled(this.pendingOperations);
+    }
+
+    // Stop old delegate gracefully
+    if (this.delegate) {
+      await this.delegate.stop();
+    }
+
+    // Switch to new implementation
+    this.delegate = newQueue;
+    this.stopped = false;
+
+    // Re-apply all stored subscriptions
+    for (const [group, { consumer, options }] of this.subscriptions) {
+      rootLogger.debug(
+        `Re-applying subscription for group '${group}' on queue '${this.name}'`
+      );
+      await this.delegate.consume(consumer, options);
+    }
+  }
+
+  /**
+   * Get the underlying delegate for direct access (use sparingly)
+   */
+  getDelegate(): Queue<T> | undefined {
+    return this.delegate;
+  }
+
+  private ensureDelegate(): Queue<T> {
+    if (!this.delegate) {
+      throw new Error(
+        `Queue '${this.name}' not initialized. Ensure QueueManager.loadConfiguration() has been called.`
+      );
+    }
+    if (this.stopped) {
+      throw new Error(`Queue '${this.name}' has been stopped.`);
+    }
+    return this.delegate;
+  }
+
+  private trackOperation<R>(operation: Promise<R>): Promise<R> {
+    this.pendingOperations.push(operation);
+    return operation.finally(() => {
+      this.pendingOperations = this.pendingOperations.filter(
+        (p) => p !== operation
+      );
+    });
+  }
+
+  async enqueue(
+    data: T,
+    options?: {
+      priority?: number;
+      startDelay?: number;
+      jobId?: string;
+    }
+  ): Promise<string> {
+    const delegate = this.ensureDelegate();
+    return this.trackOperation(delegate.enqueue(data, options));
+  }
+
+  async consume(
+    consumer: QueueConsumer<T>,
+    options: ConsumeOptions
+  ): Promise<void> {
+    // Store subscription for replay after backend switch
+    this.subscriptions.set(options.consumerGroup, { consumer, options });
+
+    // If we have a delegate, apply immediately
+    if (this.delegate && !this.stopped) {
+      await this.delegate.consume(consumer, options);
+    }
+  }
+
+  async scheduleRecurring(
+    data: T,
+    options: {
+      jobId: string;
+      intervalSeconds: number;
+      startDelay?: number;
+      priority?: number;
+    }
+  ): Promise<string> {
+    const delegate = this.ensureDelegate();
+    return this.trackOperation(delegate.scheduleRecurring(data, options));
+  }
+
+  async cancelRecurring(jobId: string): Promise<void> {
+    const delegate = this.ensureDelegate();
+    return this.trackOperation(delegate.cancelRecurring(jobId));
+  }
+
+  async listRecurringJobs(): Promise<string[]> {
+    const delegate = this.ensureDelegate();
+    return delegate.listRecurringJobs();
+  }
+
+  async getRecurringJobDetails(
+    jobId: string
+  ): Promise<RecurringJobDetails<T> | undefined> {
+    const delegate = this.ensureDelegate();
+    return delegate.getRecurringJobDetails(jobId);
+  }
+
+  async getInFlightCount(): Promise<number> {
+    const delegate = this.ensureDelegate();
+    return delegate.getInFlightCount();
+  }
+
+  async testConnection(): Promise<void> {
+    const delegate = this.ensureDelegate();
+    return delegate.testConnection();
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true;
+
+    // Wait for pending operations
+    if (this.pendingOperations.length > 0) {
+      await Promise.allSettled(this.pendingOperations);
+    }
+
+    if (this.delegate) {
+      await this.delegate.stop();
+    }
+  }
+
+  async getStats(): Promise<QueueStats> {
+    const delegate = this.ensureDelegate();
+    return delegate.getStats();
+  }
+
+  /**
+   * Get subscription count (for testing/debugging)
+   */
+  getSubscriptionCount(): number {
+    return this.subscriptions.size;
+  }
+}

package/src/services/service-registry.ts

@@ -0,0 +1,35 @@
+import { ServiceRef } from "@checkstack/backend-api";
+import type { PluginMetadata } from "@checkstack/common";
+
+type ServiceFactory<T> = (metadata: PluginMetadata) => T | Promise<T>;
+
+export class ServiceRegistry {
+  private services = new Map<string, unknown>();
+  private factories = new Map<string, ServiceFactory<unknown>>();
+
+  register<T>(ref: ServiceRef<T>, impl: T) {
+    this.services.set(ref.id, impl);
+  }
+
+  registerFactory<T>(ref: ServiceRef<T>, factory: ServiceFactory<T>) {
+    this.factories.set(ref.id, factory as ServiceFactory<unknown>);
+  }
+
+  async get<T>(ref: ServiceRef<T>, metadata: PluginMetadata): Promise<T> {
+    // 1. Try Factory (Scoped)
+    const factory = this.factories.get(ref.id);
+    if (factory) {
+      return (await factory(metadata)) as T;
+    }
+
+    // 2. Try Global Service
+    const service = this.services.get(ref.id);
+    if (service) {
+      return service as T;
+    }
+
+    throw new Error(
+      `Service '${ref.id}' not found for plugin '${metadata.pluginId}'`
+    );
+  }
+}

package/src/test-preload.ts

@@ -0,0 +1,114 @@
+/**
+ * Test Preload File
+ *
+ * This file is loaded BEFORE any test file runs (via bunfig.toml).
+ * It ensures mock.module() is called before mocked modules are imported.
+ */
+
+import { mock } from "bun:test";
+import {
+  createMockDbModule,
+  createMockLoggerModule,
+  createMockLogger,
+} from "@checkstack/test-utils-backend";
+import { coreServices } from "@checkstack/backend-api";
+import path from "node:path";
+
+// Get absolute paths to the modules we need to mock
+const backendSrcDir = path.join(__dirname);
+const dbPath = path.join(backendSrcDir, "db");
+const loggerPath = path.join(backendSrcDir, "logger");
+const coreServicesPath = path.join(
+  backendSrcDir,
+  "plugin-manager",
+  "core-services"
+);
+
+// Mock database module with absolute path
+mock.module(dbPath, () => createMockDbModule());
+
+// Mock logger module with absolute path
+mock.module(loggerPath, () => createMockLoggerModule());
+
+/**
+ * Mock core-services to register mock factories that DON'T access DATABASE_URL.
+ *
+ * The real issue: core-services.ts line 79 directly accesses process.env.DATABASE_URL
+ * inside the database factory function. This happens at RUNTIME when the factory
+ * is called, not at import time. Module mocking can't prevent it.
+ *
+ * Solution: Provide a mock version of registerCoreServices that registers
+ * test-safe factories.
+ */
+mock.module(coreServicesPath, () => ({
+  registerCoreServices: ({
+    registry,
+  }: {
+    registry: {
+      registerFactory: (ref: { id: string }, factory: unknown) => void;
+      register: (ref: { id: string }, impl: unknown) => void;
+    };
+  }) => {
+    // Register mock database factory - returns empty object, no DATABASE_URL check
+    registry.registerFactory(coreServices.database, () => ({}));
+
+    // Register mock logger factory
+    registry.registerFactory(coreServices.logger, () => createMockLogger());
+
+    // Register mock auth factory
+    registry.registerFactory(coreServices.auth, () => ({
+      authenticate: async () => {},
+      getCredentials: async () => ({ headers: {} }),
+      getAnonymousPermissions: async () => [],
+    }));
+
+    // Register mock fetch factory
+    registry.registerFactory(coreServices.fetch, () => ({
+      fetch: async () => new Response(),
+      forPlugin: () => ({
+        fetch: async () => new Response(),
+        get: async () => new Response(),
+        post: async () => new Response(),
+        put: async () => new Response(),
+        patch: async () => new Response(),
+        delete: async () => new Response(),
+      }),
+    }));
+
+    // Register mock RPC client factory
+    registry.registerFactory(coreServices.rpcClient, () => ({
+      forPlugin: () => ({}),
+    }));
+
+    // Register mock health check registry (singleton) - with actual storage
+    const strategies = new Map<string, unknown>();
+    registry.registerFactory(coreServices.healthCheckRegistry, () => ({
+      register: (strategy: { id: string }) => {
+        strategies.set(strategy.id, strategy);
+      },
+      getStrategy: (id: string) => strategies.get(id),
+      getAllStrategies: () => [...strategies.values()],
+    }));
+
+    // Register mock RPC service factory
+    registry.registerFactory(coreServices.rpc, () => ({
+      registerRouter: () => {},
+      registerHttpHandler: () => {},
+    }));
+
+    // Register mock config factory
+    registry.registerFactory(coreServices.config, () => ({
+      get: async () => {},
+      set: async () => {},
+      delete: async () => {},
+    }));
+
+    // Register mock EventBus factory
+    registry.registerFactory(coreServices.eventBus, () => ({
+      emit: async () => {},
+      emitLocal: async () => {},
+      // eslint-disable-next-line unicorn/consistent-function-scoping
+      subscribe: async () => () => {},
+    }));
+  },
+}));

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

@@ -0,0 +1,383 @@
+import { describe, it, expect, beforeEach, mock } from "bun:test";
+import {
+  extractPluginMetadata,
+  discoverLocalPlugins,
+  syncPluginsToDatabase,
+  type PluginMetadata,
+} from "./plugin-discovery";
+import fs from "node:fs";
+import path from "node:path";
+
+// Mock filesystem for testing
+const mockExistsSync = mock(() => true);
+const mockReadFileSync = mock(() => "{}");
+const mockReaddirSync = mock(() => []);
+
+mock.module("node:fs", () => {
+  const exports = {
+    existsSync: mockExistsSync,
+    readFileSync: mockReadFileSync,
+    readdirSync: mockReaddirSync,
+  };
+  return {
+    ...exports,
+    default: exports,
+  };
+});
+
+describe("extractPluginMetadata", () => {
+  beforeEach(() => {
+    mockExistsSync.mockClear();
+    mockReadFileSync.mockClear();
+    mockExistsSync.mockReturnValue(true);
+  });
+
+  it("should extract metadata from valid backend plugin", () => {
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        name: "@checkstack/test-backend",
+        version: "0.0.1",
+        type: "module",
+      })
+    );
+
+    const result = extractPluginMetadata({
+      pluginDir: "/fake/path/test-backend",
+    });
+
+    expect(result).toEqual({
+      packageName: "@checkstack/test-backend",
+      pluginPath: "/fake/path/test-backend",
+      type: "backend",
+      enabled: true,
+    });
+  });
+
+  it("should extract metadata from valid frontend plugin", () => {
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        name: "@checkstack/test-frontend",
+      })
+    );
+
+    const result = extractPluginMetadata({
+      pluginDir: "/fake/path/test-frontend",
+    });
+
+    expect(result?.type).toBe("frontend");
+  });
+
+  it("should extract metadata from valid common plugin", () => {
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        name: "@checkstack/test-common",
+      })
+    );
+
+    const result = extractPluginMetadata({
+      pluginDir: "/fake/path/test-common",
+    });
+
+    expect(result?.type).toBe("common");
+  });
+
+  it("should return undefined if package.json is missing", () => {
+    mockExistsSync.mockReturnValue(false);
+
+    const result = extractPluginMetadata({
+      pluginDir: "/fake/path/invalid",
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it("should return undefined if package.json has no name field", () => {
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        version: "0.0.1",
+      })
+    );
+
+    const result = extractPluginMetadata({
+      pluginDir: "/fake/path/invalid",
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it("should return undefined for non-plugin core (wrong suffix)", () => {
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        name: "@checkstack/not-a-plugin",
+      })
+    );
+
+    const result = extractPluginMetadata({
+      pluginDir: "/fake/path/not-a-plugin",
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it("should return undefined if package.json is malformed", () => {
+    mockReadFileSync.mockReturnValue("invalid json{");
+
+    const result = extractPluginMetadata({
+      pluginDir: "/fake/path/invalid",
+    });
+
+    expect(result).toBeUndefined();
+  });
+});
+
+describe("discoverLocalPlugins", () => {
+  beforeEach(() => {
+    mockExistsSync.mockClear();
+    mockReadFileSync.mockClear();
+    mockReaddirSync.mockClear();
+    mockExistsSync.mockReturnValue(true);
+  });
+
+  it("should discover all valid backend plugins from both core/ and plugins/", () => {
+    // Mock different contents for core/ and plugins/ directories
+    mockReaddirSync.mockImplementation(((dirPath: string) => {
+      if (dirPath.includes("core")) {
+        return [
+          { isDirectory: () => true, name: "auth-backend" },
+          { isDirectory: () => false, name: "README.md" }, // File, should skip
+        ];
+      }
+      if (dirPath.includes("plugins")) {
+        return [
+          { isDirectory: () => true, name: "catalog-backend" },
+          { isDirectory: () => true, name: "invalid-plugin" }, // No -backend suffix
+        ];
+      }
+      return [];
+    }) as typeof mockReaddirSync);
+
+    // Mock package.json reads
+    mockReadFileSync.mockImplementation(((filePath: string) => {
+      if (filePath.includes("auth-backend")) {
+        return JSON.stringify({ name: "@checkstack/auth-backend" });
+      }
+      if (filePath.includes("catalog-backend")) {
+        return JSON.stringify({ name: "@checkstack/catalog-backend" });
+      }
+      if (filePath.includes("invalid-plugin")) {
+        return JSON.stringify({ name: "@checkstack/invalid-plugin" });
+      }
+      return "{}";
+    }) as typeof mockReadFileSync);
+
+    const result = discoverLocalPlugins({ workspaceRoot: "/fake/workspace" });
+
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.packageName)).toContain(
+      "@checkstack/auth-backend"
+    );
+    expect(result.map((r) => r.packageName)).toContain(
+      "@checkstack/catalog-backend"
+    );
+  });
+
+  it("should filter plugins by type when type parameter is provided", () => {
+    // Mock: core/ has backend and frontend, plugins/ has common
+    mockReaddirSync.mockImplementation(((dirPath: string) => {
+      if (dirPath.includes("core")) {
+        return [
+          { isDirectory: () => true, name: "auth-backend" },
+          { isDirectory: () => true, name: "auth-frontend" },
+        ];
+      }
+      if (dirPath.includes("plugins")) {
+        return [{ isDirectory: () => true, name: "auth-common" }];
+      }
+      return [];
+    }) as typeof mockReaddirSync);
+
+    mockReadFileSync.mockImplementation(((filePath: string) => {
+      if (filePath.includes("auth-backend")) {
+        return JSON.stringify({ name: "@checkstack/auth-backend" });
+      }
+      if (filePath.includes("auth-frontend")) {
+        return JSON.stringify({ name: "@checkstack/auth-frontend" });
+      }
+      if (filePath.includes("auth-common")) {
+        return JSON.stringify({ name: "@checkstack/auth-common" });
+      }
+      return "{}";
+    }) as typeof mockReadFileSync);
+
+    const backendResult = discoverLocalPlugins({
+      workspaceRoot: "/fake/workspace",
+      type: "backend",
+    });
+    expect(backendResult).toHaveLength(1);
+    expect(backendResult[0].type).toBe("backend");
+
+    const frontendResult = discoverLocalPlugins({
+      workspaceRoot: "/fake/workspace",
+      type: "frontend",
+    });
+    expect(frontendResult).toHaveLength(1);
+    expect(frontendResult[0].type).toBe("frontend");
+  });
+
+  it("should return empty array if neither core/ nor plugins/ directory exists", () => {
+    mockExistsSync.mockReturnValue(false);
+
+    const result = discoverLocalPlugins({ workspaceRoot: "/fake/workspace" });
+
+    expect(result).toEqual([]);
+  });
+
+  it("should skip directories without valid package.json", () => {
+    mockReaddirSync.mockImplementation(((dirPath: string) => {
+      if (dirPath.includes("core")) {
+        return [{ isDirectory: () => true, name: "broken-backend" }];
+      }
+      return [];
+    }) as typeof mockReaddirSync);
+
+    mockExistsSync.mockImplementation(((filePath: string) => {
+      // core/ and plugins/ directories exist
+      if (filePath.endsWith("core") || filePath.endsWith("plugins")) {
+        return true;
+      }
+      // package.json doesn't exist for broken-backend
+      return !filePath.includes("broken-backend");
+    }) as typeof mockExistsSync);
+
+    const result = discoverLocalPlugins({ workspaceRoot: "/fake/workspace" });
+
+    expect(result).toEqual([]);
+  });
+});
+
+describe("syncPluginsToDatabase", () => {
+  let mockDb: any;
+
+  beforeEach(() => {
+    mockDb = {
+      select: mock(() => ({
+        from: mock(() => ({
+          where: mock(() => ({
+            limit: mock(() => Promise.resolve([])),
+          })),
+        })),
+      })),
+      insert: mock(() => ({
+        values: mock(() => Promise.resolve()),
+      })),
+      update: mock(() => ({
+        set: mock(() => ({
+          where: mock(() => Promise.resolve()),
+        })),
+      })),
+    };
+  });
+
+  it("should insert new plugin that doesn't exist in database", async () => {
+    const localPlugins: PluginMetadata[] = [
+      {
+        packageName: "@checkstack/new-backend",
+        pluginPath: "/workspace/plugins/new-backend",
+        type: "backend",
+        enabled: true,
+      },
+    ];
+
+    // Mock: plugin doesn't exist
+    mockDb.select.mockReturnValue({
+      from: mock(() => ({
+        where: mock(() => ({
+          limit: mock(() => Promise.resolve([])),
+        })),
+      })),
+    });
+
+    await syncPluginsToDatabase({ localPlugins, db: mockDb });
+
+    expect(mockDb.insert).toHaveBeenCalled();
+    const insertCall = mockDb.insert.mock.results[0].value;
+    expect(insertCall.values).toHaveBeenCalledWith({
+      name: "@checkstack/new-backend",
+      path: "/workspace/plugins/new-backend",
+      type: "backend",
+      enabled: true,
+      isUninstallable: false,
+    });
+  });
+
+  it("should update path for renamed local plugin", async () => {
+    const localPlugins: PluginMetadata[] = [
+      {
+        packageName: "@checkstack/renamed-backend",
+        pluginPath: "/workspace/plugins/new-location",
+        type: "backend",
+        enabled: true,
+      },
+    ];
+
+    // Mock: plugin exists as local plugin (isUninstallable=false)
+    mockDb.select.mockReturnValue({
+      from: mock(() => ({
+        where: mock(() => ({
+          limit: mock(() =>
+            Promise.resolve([
+              {
+                name: "@checkstack/renamed-backend",
+                path: "/workspace/plugins/old-location",
+                isUninstallable: false,
+              },
+            ])
+          ),
+        })),
+      })),
+    });
+
+    await syncPluginsToDatabase({ localPlugins, db: mockDb });
+
+    expect(mockDb.update).toHaveBeenCalled();
+    const updateCall = mockDb.update.mock.results[0].value;
+    expect(updateCall.set).toHaveBeenCalledWith({
+      path: "/workspace/plugins/new-location",
+      type: "backend",
+    });
+  });
+
+  it("should not modify remotely installed plugins", async () => {
+    const localPlugins: PluginMetadata[] = [
+      {
+        packageName: "@checkstack/remote-backend",
+        pluginPath: "/workspace/plugins/remote-backend",
+        type: "backend",
+        enabled: true,
+      },
+    ];
+
+    // Mock: plugin exists as remote plugin (isUninstallable=true)
+    mockDb.select.mockReturnValue({
+      from: mock(() => ({
+        where: mock(() => ({
+          limit: mock(() =>
+            Promise.resolve([
+              {
+                name: "@checkstack/remote-backend",
+                path: "/runtime/node_modules/@checkstack/remote-backend",
+                isUninstallable: true,
+              },
+            ])
+          ),
+        })),
+      })),
+    });
+
+    await syncPluginsToDatabase({ localPlugins, db: mockDb });
+
+    // Should not call insert or update
+    expect(mockDb.insert).not.toHaveBeenCalled();
+    expect(mockDb.update).not.toHaveBeenCalled();
+  });
+});