@checkstack/backend 0.8.2 → 0.9.1

package/src/services/cache-manager.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { z } from "zod";
+import { CacheManagerImpl } from "./cache-manager";
+import { CachePluginRegistryImpl } from "./cache-plugin-registry";
+import type { CachePlugin, CacheProvider, CacheStats } from "@checkstack/cache-api";
+import type { ConfigService, Logger } from "@checkstack/backend-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+class FakeInMemoryCache implements CacheProvider {
+  store = new Map<string, unknown>();
+  hits = 0;
+  misses = 0;
+
+  async get<T>(key: string): Promise<T | undefined> {
+    if (this.store.has(key)) {
+      this.hits++;
+      return this.store.get(key) as T;
+    }
+    this.misses++;
+    return undefined;
+  }
+  async set<T>(key: string, value: T): Promise<void> {
+    this.store.set(key, value);
+  }
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+  async deleteByPrefix(): Promise<number> {
+    return 0;
+  }
+  async has(key: string): Promise<boolean> {
+    return this.store.has(key);
+  }
+  async getStats(): Promise<CacheStats> {
+    return {
+      keyCount: this.store.size,
+      sizeBytes: null,
+      hits: this.hits,
+      misses: this.misses,
+      scope: "instance",
+    };
+  }
+}
+
+const memoryConfigSchema = z.record(z.string(), z.unknown());
+
+const createMemoryPlugin = (
+  factory: () => FakeInMemoryCache,
+): CachePlugin<unknown> => ({
+  id: "memory",
+  displayName: "Memory",
+  configVersion: 1,
+  configSchema: memoryConfigSchema,
+  createProvider: () => factory(),
+});
+
+class StubConfigService implements ConfigService {
+  store = new Map<string, unknown>();
+  async set<T>(configId: string, _s: unknown, _v: number, data: T) {
+    this.store.set(configId, data);
+  }
+  async get<T>(configId: string): Promise<T | undefined> {
+    return this.store.get(configId) as T | undefined;
+  }
+  async getRedacted<T>(configId: string): Promise<Partial<T> | undefined> {
+    return this.store.get(configId) as Partial<T> | undefined;
+  }
+  async delete(configId: string): Promise<void> {
+    this.store.delete(configId);
+  }
+  async list(): Promise<string[]> {
+    return [...this.store.keys()];
+  }
+}
+
+describe("CacheManagerImpl provider proxy", () => {
+  let registry: CachePluginRegistryImpl;
+  let configService: StubConfigService;
+  let logger: Logger;
+  let manager: CacheManagerImpl;
+  let instances: FakeInMemoryCache[];
+
+  beforeEach(() => {
+    registry = new CachePluginRegistryImpl();
+    configService = new StubConfigService();
+    logger = createMockLogger() as unknown as Logger;
+    instances = [];
+    registry.register(
+      createMemoryPlugin(() => {
+        const inst = new FakeInMemoryCache();
+        instances.push(inst);
+        return inst;
+      }),
+    );
+    manager = new CacheManagerImpl(registry, configService, logger);
+  });
+
+  it("returns the same proxy reference across calls", async () => {
+    const a = manager.getProvider();
+    const b = manager.getProvider();
+    expect(a).toBe(b);
+  });
+
+  it("delegates writes to the active provider after loadConfiguration", async () => {
+    const provider = manager.getProvider();
+    await manager.loadConfiguration();
+    await provider.set("foo", "bar");
+    expect(instances[0].store.get("foo")).toBe("bar");
+  });
+
+  it("keeps a captured proxy reference live across setActiveBackend", async () => {
+    await manager.loadConfiguration();
+    const captured = manager.getProvider();
+    await captured.set("before", 1);
+
+    await manager.setActiveBackend("memory", {
+      maxEntries: 5000,
+      sweepIntervalMs: 30_000,
+    });
+
+    // The captured reference must now write to the NEW active provider,
+    // not the orphaned old one.
+    await captured.set("after", 2);
+
+    const oldInstance = instances[0];
+    const newInstance = instances.at(-1)!;
+    expect(oldInstance).not.toBe(newInstance);
+    expect(oldInstance.store.has("after")).toBe(false);
+    expect(newInstance.store.has("after")).toBe(true);
+  });
+
+  it("getStats reads from the currently active provider", async () => {
+    await manager.loadConfiguration();
+    const provider = manager.getProvider();
+    await provider.set("k1", "v1");
+    await provider.get("k1"); // hit
+    await provider.get("missing"); // miss
+
+    const stats = await provider.getStats!();
+    expect(stats.keyCount).toBe(1);
+    expect(stats.hits).toBe(1);
+    expect(stats.misses).toBe(1);
+  });
+
+  it("getStats returns all-null when active provider has no getStats impl", async () => {
+    // Plugin whose provider doesn't implement getStats.
+    const minimalPlugin: CachePlugin<unknown> = {
+      id: "noStats",
+      displayName: "No stats",
+      configVersion: 1,
+      configSchema: memoryConfigSchema,
+      createProvider: (): CacheProvider => ({
+        get: async () => undefined,
+        set: async () => {},
+        delete: async () => {},
+        deleteByPrefix: async () => 0,
+        has: async () => false,
+      }),
+    };
+    registry.register(minimalPlugin);
+
+    await manager.setActiveBackend("noStats", {});
+    const stats = await manager.getProvider().getStats!();
+    expect(stats).toEqual({
+      keyCount: null,
+      sizeBytes: null,
+      hits: null,
+      misses: null,
+      scope: "instance",
+    });
+  });
+});

package/src/services/cache-manager.ts

@@ -1,4 +1,10 @@
-import type { CacheManager, CacheProvider } from "@checkstack/cache-api";
+import type {
+  CacheManager,
+  CacheProvider,
+  CacheStats,
+  ListEntriesOptions,
+  ListEntriesResult,
+} from "@checkstack/cache-api";
 import type { CachePluginRegistryImpl } from "./cache-plugin-registry";
 import type { Logger, ConfigService } from "@checkstack/backend-api";
 import { z } from "zod";
@@ -18,6 +24,10 @@ type ActiveCachePointer = z.infer<typeof activeCachePointerSchema>;
 /**
  * A no-op CacheProvider used before any backend is configured.
  * All operations are safe to call but behave as if the cache is empty.
+ *
+ * Held only as the initial value of `activeProvider` until
+ * `loadConfiguration()` runs; consumers always interact with the stable
+ * proxy below, so they pick up the real provider as soon as it's ready.
  */
 const nullProvider: CacheProvider = {
   // eslint-disable-next-line unicorn/no-useless-undefined
@@ -31,8 +41,18 @@ const nullProvider: CacheProvider = {
 /**
  * CacheManagerImpl handles cache provider lifecycle and backend switching.
  *
- * Simpler than QueueManagerImpl — no proxy pattern needed since cache is
- * stateless key/value. The active provider is replaced atomically on backend switch.
+ * `getProvider()` returns a single stable proxy whose methods delegate to
+ * whichever provider is currently active. This means:
+ *
+ *  - Plugins that capture the proxy at init time (e.g. via
+ *    `createCachedScope`) keep functioning across backend switches and
+ *    don't write into orphaned providers.
+ *  - The Infrastructure runtime panel reads stats from the same instance
+ *    plugins write to — no split-brain.
+ *
+ * The earlier "no proxy pattern needed since cache is stateless key/value"
+ * comment was wrong: in-memory backends are stateful and replacing the
+ * active reference would orphan their state.
  */
 export class CacheManagerImpl implements CacheManager {
   private activePluginId: string = "memory";
@@ -42,12 +62,49 @@ export class CacheManagerImpl implements CacheManager {
   };
   private configVersion: number = 0;
   private activeProvider: CacheProvider = nullProvider;
+  private readonly providerProxy: CacheProvider;
 
   constructor(
     private registry: CachePluginRegistryImpl,
     private configService: ConfigService,
     private logger: Logger,
-  ) {}
+  ) {
+    this.providerProxy = this.createProviderProxy();
+  }
+
+  private createProviderProxy(): CacheProvider {
+    return {
+      get: <T>(key: string) => this.activeProvider.get<T>(key),
+      set: <T>(key: string, value: T, ttlMs?: number) =>
+        this.activeProvider.set<T>(key, value, ttlMs),
+      delete: (key: string) => this.activeProvider.delete(key),
+      deleteByPrefix: (prefix: string) =>
+        this.activeProvider.deleteByPrefix(prefix),
+      has: (key: string) => this.activeProvider.has(key),
+      getStats: async (): Promise<CacheStats> => {
+        const provider = this.activeProvider;
+        if (provider.getStats) {
+          return provider.getStats();
+        }
+        return {
+          keyCount: null,
+          sizeBytes: null,
+          hits: null,
+          misses: null,
+          scope: "instance",
+        };
+      },
+      listEntries: async (
+        opts: ListEntriesOptions,
+      ): Promise<ListEntriesResult> => {
+        const provider = this.activeProvider;
+        if (!provider.listEntries) {
+          return { items: [], total: 0, hasMore: false };
+        }
+        return provider.listEntries(opts);
+      },
+    };
+  }
 
   async loadConfiguration(): Promise<void> {
     try {
@@ -83,11 +140,10 @@ export class CacheManagerImpl implements CacheManager {
         );
       }
 
-      // Initialize the active provider
       this.initializeProvider();
     } catch (error) {
       this.logger.error("Failed to load cache configuration", error);
-      // Continue with defaults — nullProvider is already set
+      // Continue with defaults — nullProvider is already set behind the proxy.
     }
   }
 
@@ -113,8 +169,12 @@ export class CacheManagerImpl implements CacheManager {
     }
   }
 
+  /**
+   * Returns the stable proxy. The same instance is returned for the
+   * lifetime of the manager, so callers can safely capture it once.
+   */
   getProvider(): CacheProvider {
-    return this.activeProvider;
+    return this.providerProxy;
   }
 
   getActivePlugin(): string {
@@ -126,21 +186,17 @@ export class CacheManagerImpl implements CacheManager {
   }
 
   async setActiveBackend(pluginId: string, config: unknown): Promise<void> {
-    // 1. Validate plugin exists
     const newPlugin = this.registry.getPlugin(pluginId);
     if (!newPlugin) {
       throw new Error(`Cache plugin '${pluginId}' not found`);
     }
 
-    // 2. Validate config against schema
     newPlugin.configSchema.parse(config);
 
-    // 3. Create new provider (acts as connection test)
     this.logger.info("🔍 Testing new cache provider...");
     let newProvider: CacheProvider;
     try {
       newProvider = newPlugin.createProvider(config, this.logger);
-      // Quick smoke test
       await newProvider.set("__test__", true, 1000);
       await newProvider.delete("__test__");
       this.logger.info("✅ Cache provider test successful");
@@ -150,20 +206,17 @@ export class CacheManagerImpl implements CacheManager {
       throw new Error(`Failed to create cache provider: ${message}`);
     }
 
-    // 4. Stop old provider if it has a stop method
     const oldProvider = this.activeProvider;
     if ("stop" in oldProvider && typeof oldProvider.stop === "function") {
       await (oldProvider as { stop: () => Promise<void> }).stop();
     }
 
-    // 5. Switch to new provider
     const oldPluginId = this.activePluginId;
     this.activePluginId = pluginId;
     this.activeConfig = config;
     this.configVersion++;
     this.activeProvider = newProvider;
 
-    // 6. Persist configuration
     await this.configService.set(
       pluginId,
       newPlugin.configSchema,

package/src/services/compatibility-checker.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from "bun:test";
+import { checkCompatibility } from "./compatibility-checker";
+import type { InstallPackageMetadata } from "@checkstack/common";
+
+const minimalPkg = (
+  override: Partial<InstallPackageMetadata>,
+): InstallPackageMetadata => ({
+  name: "@scope/example",
+  version: "1.0.0",
+  description: "example",
+  author: "test",
+  license: "Elastic-2.0",
+  checkstack: { type: "backend", pluginId: "example" },
+  ...override,
+});
+
+describe("checkCompatibility", () => {
+  it("passes when every @checkstack/* dep is satisfied by loaded versions", () => {
+    const pkg = minimalPkg({
+      dependencies: {
+        "@checkstack/backend-api": "^1.0.0",
+        "@checkstack/common": "^1.0.0",
+      },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map([
+        ["@checkstack/backend-api", "1.2.3"],
+        ["@checkstack/common", "1.5.0"],
+      ]),
+    });
+    expect(issues).toEqual([]);
+  });
+
+  it("ignores non-@checkstack deps", () => {
+    const pkg = minimalPkg({
+      dependencies: { lodash: "^4.0.0", react: "^18.0.0" },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map(),
+    });
+    expect(issues).toEqual([]);
+  });
+
+  it("flags missing @checkstack/* dependency not in bundle", () => {
+    const pkg = minimalPkg({
+      dependencies: { "@checkstack/missing-pkg": "^1.0.0" },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map(),
+    });
+    expect(issues).toHaveLength(1);
+    expect(issues[0].kind).toBe("missing-dependency");
+    expect(issues[0].dependency).toBe("@checkstack/missing-pkg");
+  });
+
+  it("flags semver mismatch against loaded platform version", () => {
+    const pkg = minimalPkg({
+      dependencies: { "@checkstack/backend-api": "^2.0.0" },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map([["@checkstack/backend-api", "1.0.0"]]),
+    });
+    expect(issues).toHaveLength(1);
+    expect(issues[0].kind).toBe("version-mismatch");
+    expect(issues[0].declared).toBe("^2.0.0");
+    expect(issues[0].actual).toBe("1.0.0");
+  });
+
+  it("rejects unresolved workspace:* ranges (must be resolved at pack time)", () => {
+    const pkg = minimalPkg({
+      dependencies: { "@checkstack/backend-api": "workspace:*" },
+    });
+    const issues = checkCompatibility({
+      packages: [pkg],
+      loadedVersions: new Map([["@checkstack/backend-api", "1.0.0"]]),
+    });
+    expect(issues).toHaveLength(1);
+    expect(issues[0].kind).toBe("version-mismatch");
+    expect(issues[0].declared).toBe("workspace:*");
+  });
+
+  it("satisfies bundle-internal deps from sibling packages, not platform versions", () => {
+    const primary = minimalPkg({
+      name: "@scope/foo-backend",
+      version: "1.0.0",
+      dependencies: { "@scope/foo-common": "^1.0.0" },
+    });
+    const sibling = minimalPkg({
+      name: "@scope/foo-common",
+      version: "1.0.0",
+      checkstack: { type: "common", pluginId: "foo" },
+    });
+
+    const issues = checkCompatibility({
+      packages: [primary, sibling],
+      loadedVersions: new Map(), // platform doesn't have @scope/foo-common
+    });
+    // The dep is `@scope/foo-common`, not `@checkstack/*`, so it isn't
+    // checked at all. But verify the check would also pass for the
+    // (more interesting) `@checkstack/*` case:
+  });
+
+  it("satisfies bundle-internal @checkstack/* dep from a sibling package", () => {
+    const primary = minimalPkg({
+      name: "@checkstack/foo-backend",
+      version: "1.0.0",
+      dependencies: { "@checkstack/foo-common": "^1.0.0" },
+    });
+    const sibling = minimalPkg({
+      name: "@checkstack/foo-common",
+      version: "1.0.0",
+      checkstack: { type: "common", pluginId: "foo" },
+    });
+
+    const issues = checkCompatibility({
+      packages: [primary, sibling],
+      loadedVersions: new Map(),
+    });
+    expect(issues).toEqual([]);
+  });
+
+  it("flags bundle-internal dep when version doesn't match", () => {
+    const primary = minimalPkg({
+      name: "@checkstack/foo-backend",
+      version: "1.0.0",
+      dependencies: { "@checkstack/foo-common": "^2.0.0" },
+    });
+    const sibling = minimalPkg({
+      name: "@checkstack/foo-common",
+      version: "1.0.0",
+      checkstack: { type: "common", pluginId: "foo" },
+    });
+
+    const issues = checkCompatibility({
+      packages: [primary, sibling],
+      loadedVersions: new Map(),
+    });
+    expect(issues).toHaveLength(1);
+    expect(issues[0].kind).toBe("version-mismatch");
+    expect(issues[0].dependency).toBe("@checkstack/foo-common");
+  });
+});

package/src/services/compatibility-checker.ts

@@ -0,0 +1,137 @@
+import path from "node:path";
+import fs from "node:fs";
+import semver from "semver";
+import type { InstallPackageMetadata } from "@checkstack/common";
+import type { CompatibilityIssue } from "@checkstack/pluginmanager-common";
+import { rootLogger } from "../logger";
+
+/**
+ * Builds a snapshot of every `@checkstack/*` package the current process
+ * can resolve, with its installed `version`. Used as the source of truth
+ * for compatibility checks.
+ *
+ * We don't need a separate "core version" — every package version is its
+ * own contract.
+ */
+export function loadCheckstackPackageVersions({
+  workspaceRoot,
+  runtimeDir,
+}: {
+  workspaceRoot: string;
+  runtimeDir: string;
+}): Map<string, string> {
+  const versions = new Map<string, string>();
+
+  const walk = (dir: string) => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const pkgJsonPath = path.join(dir, entry.name, "package.json");
+      if (!fs.existsSync(pkgJsonPath)) continue;
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+        if (
+          typeof pkg.name === "string" &&
+          pkg.name.startsWith("@checkstack/") &&
+          typeof pkg.version === "string"
+         && // First-write wins: monorepo source wins over runtime_plugins
+          !versions.has(pkg.name)) {
+            versions.set(pkg.name, pkg.version);
+          }
+      } catch (error) {
+        rootLogger.debug(`Failed to read ${pkgJsonPath}`, error);
+      }
+    }
+  };
+
+  walk(path.join(workspaceRoot, "core"));
+  walk(path.join(workspaceRoot, "plugins"));
+  walk(path.join(runtimeDir, "node_modules"));
+  walk(path.join(runtimeDir, "node_modules", "@checkstack"));
+
+  return versions;
+}
+
+/**
+ * Check that every `@checkstack/*` dep declared by a plugin (and its bundle
+ * siblings) is satisfiable from the loaded package set OR from another
+ * package in the same install bundle.
+ *
+ * Returns an empty array when compatible, a populated array of issues otherwise.
+ */
+export function checkCompatibility({
+  packages,
+  loadedVersions,
+}: {
+  packages: InstallPackageMetadata[];
+  loadedVersions: Map<string, string>;
+}): CompatibilityIssue[] {
+  const issues: CompatibilityIssue[] = [];
+
+  // Bundle-internal deps: plugins in the same install set satisfy each other.
+  const bundleVersions = new Map<string, string>();
+  for (const pkg of packages) {
+    bundleVersions.set(pkg.name, pkg.version);
+  }
+
+  for (const pkg of packages) {
+    const deps = pkg.dependencies ?? {};
+    for (const [depName, declaredRange] of Object.entries(deps)) {
+      if (!depName.startsWith("@checkstack/")) continue;
+
+      // Skip workspace ranges — these only appear in monorepo source files,
+      // never in published tarballs (the pack CLI rewrites them). If we see
+      // one here it's a sign the plugin wasn't packed via our CLI.
+      if (declaredRange.startsWith("workspace:")) {
+        issues.push({
+          pluginName: pkg.name,
+          kind: "version-mismatch",
+          dependency: depName,
+          declared: declaredRange,
+          message: `Plugin '${pkg.name}' depends on '${depName}' with unresolved 'workspace:*' range. Re-pack with '@checkstack/scripts plugin-pack' which resolves workspace ranges to concrete versions.`,
+        });
+        continue;
+      }
+
+      const bundleVersion = bundleVersions.get(depName);
+      if (bundleVersion !== undefined) {
+        if (!semver.satisfies(bundleVersion, declaredRange)) {
+          issues.push({
+            pluginName: pkg.name,
+            kind: "version-mismatch",
+            dependency: depName,
+            declared: declaredRange,
+            actual: bundleVersion,
+            message: `Plugin '${pkg.name}' requires ${depName}@${declaredRange} but the bundle ships ${bundleVersion}.`,
+          });
+        }
+        continue;
+      }
+
+      const loadedVersion = loadedVersions.get(depName);
+      if (loadedVersion === undefined) {
+        issues.push({
+          pluginName: pkg.name,
+          kind: "missing-dependency",
+          dependency: depName,
+          declared: declaredRange,
+          message: `Plugin '${pkg.name}' depends on '${depName}' which is not loaded by this platform and is not part of the install bundle.`,
+        });
+        continue;
+      }
+
+      if (!semver.satisfies(loadedVersion, declaredRange)) {
+        issues.push({
+          pluginName: pkg.name,
+          kind: "version-mismatch",
+          dependency: depName,
+          declared: declaredRange,
+          actual: loadedVersion,
+          message: `Plugin '${pkg.name}' requires ${depName}@${declaredRange} but this platform has ${loadedVersion}.`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}