@checkstack/dev-server 0.2.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@checkstack/dev-server",
+  "version": "0.2.0",
+  "description": "Local Checkstack dev server for plugin authors. Spawns the platform backend with the cwd plugin loaded, runs Vite for the frontend, and reloads on save. Used as a devDependency in plugin repos (run via `bun run dev` → `checkstack-dev`).",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "checkstack": {
+    "type": "tooling"
+  },
+  "main": "src/dev-server.ts",
+  "bin": {
+    "checkstack-dev": "./src/dev-server.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/common": "0.8.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^5.4.0"
+  },
+  "peerDependencies": {
+    "@checkstack/backend": "*",
+    "@checkstack/frontend": "*"
+  },
+  "peerDependenciesMeta": {
+    "@checkstack/backend": {
+      "optional": true
+    },
+    "@checkstack/frontend": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.2.0",
+    "@checkstack/backend": "0.9.0",
+    "@checkstack/frontend": "0.5.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/dev-deps-resolver.test.ts

@@ -0,0 +1,411 @@
+import { describe, it, expect } from "bun:test";
+import path from "node:path";
+import { resolveCorePluginDeps } from "./dev-deps-resolver";
+
+/**
+ * In-memory fixture for a virtual node_modules tree. Maps a fully
+ * qualified file path to its file contents (typically package.json
+ * stringified JSON).
+ */
+type Fs = Record<string, string>;
+
+const ROOT = "/plugin-author/repo";
+const NM = `${ROOT}/node_modules`;
+
+function makeFs(packages: Record<string, unknown>): Fs {
+  const out: Fs = {};
+  for (const [name, pkg] of Object.entries(packages)) {
+    out[`${NM}/${name}/package.json`] = JSON.stringify(pkg);
+  }
+  return out;
+}
+
+function makeResolver(fs: Fs) {
+  return (_from: string, request: string): string | undefined => {
+    // Only handle requests of the form `<pkg>/package.json` — that's all
+    // resolveCorePluginDeps issues. A real `createRequire` resolves any
+    // entry, but we don't need that fidelity here.
+    if (!request.endsWith("/package.json")) return undefined;
+    const pkgName = request.replace(/\/package\.json$/, "");
+    const candidate = `${NM}/${pkgName}/package.json`;
+    return fs[candidate] === undefined ? undefined : candidate;
+  };
+}
+
+function readFileFromFs(fs: Fs) {
+  return (p: string): string => {
+    const text = fs[p];
+    if (text === undefined) throw new Error(`ENOENT: ${p}`);
+    return text;
+  };
+}
+
+describe("resolveCorePluginDeps", () => {
+  it("returns only the auto-included providers for a plugin with no @checkstack/* backend deps", () => {
+    const fs: Fs = {
+      [`${ROOT}/package.json`]: JSON.stringify({
+        name: "@my-org/widget-backend",
+        dependencies: {
+          "@checkstack/backend-api": "^1.0.0",
+          lodash: "^4.0.0",
+        },
+        checkstack: { type: "backend", pluginId: "widget" },
+      }),
+      ...makeFs({
+        "@checkstack/backend-api": {
+          name: "@checkstack/backend-api",
+          checkstack: { type: "common" },
+        },
+        "@checkstack/queue-memory-backend": {
+          name: "@checkstack/queue-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "queue-memory" },
+        },
+        "@checkstack/cache-memory-backend": {
+          name: "@checkstack/cache-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "cache-memory" },
+        },
+      }),
+    };
+
+    const resolved = resolveCorePluginDeps({
+      pluginDir: ROOT,
+      readFile: readFileFromFs(fs),
+      resolveFrom: makeResolver(fs),
+    });
+
+    const names = resolved.map((r) => r.name).toSorted();
+    expect(names).toEqual([
+      "@checkstack/cache-memory-backend",
+      "@checkstack/queue-memory-backend",
+    ]);
+  });
+
+  it("includes a single backend dep declared in dependencies", () => {
+    const fs: Fs = {
+      [`${ROOT}/package.json`]: JSON.stringify({
+        name: "@my-org/healthcheck-rcon-backend",
+        dependencies: {
+          "@checkstack/healthcheck-backend": "^1.0.0",
+        },
+        checkstack: { type: "backend", pluginId: "healthcheck-rcon" },
+      }),
+      ...makeFs({
+        "@checkstack/healthcheck-backend": {
+          name: "@checkstack/healthcheck-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "healthcheck" },
+          dependencies: {},
+        },
+        "@checkstack/queue-memory-backend": {
+          name: "@checkstack/queue-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "queue-memory" },
+        },
+        "@checkstack/cache-memory-backend": {
+          name: "@checkstack/cache-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "cache-memory" },
+        },
+      }),
+    };
+
+    const resolved = resolveCorePluginDeps({
+      pluginDir: ROOT,
+      readFile: readFileFromFs(fs),
+      resolveFrom: makeResolver(fs),
+    });
+
+    expect(resolved.map((r) => r.name).toSorted()).toEqual([
+      "@checkstack/cache-memory-backend",
+      "@checkstack/healthcheck-backend",
+      "@checkstack/queue-memory-backend",
+    ]);
+
+    const hc = resolved.find((r) => r.name === "@checkstack/healthcheck-backend");
+    expect(hc?.modulePath).toBe(
+      path.resolve(`${NM}/@checkstack/healthcheck-backend/src/index.ts`),
+    );
+  });
+
+  it("walks transitive @checkstack/* backend deps", () => {
+    // Plugin → notification-discord-backend → notification-backend → catalog-backend
+    const fs: Fs = {
+      [`${ROOT}/package.json`]: JSON.stringify({
+        name: "@my-org/widget-backend",
+        dependencies: {
+          "@checkstack/notification-discord-backend": "^1.0.0",
+        },
+        checkstack: { type: "backend", pluginId: "widget" },
+      }),
+      ...makeFs({
+        "@checkstack/notification-discord-backend": {
+          name: "@checkstack/notification-discord-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "notification-discord" },
+          dependencies: {
+            "@checkstack/notification-backend": "^1.0.0",
+          },
+        },
+        "@checkstack/notification-backend": {
+          name: "@checkstack/notification-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "notification" },
+          dependencies: {
+            "@checkstack/catalog-backend": "^1.0.0",
+          },
+        },
+        "@checkstack/catalog-backend": {
+          name: "@checkstack/catalog-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "catalog" },
+        },
+        "@checkstack/queue-memory-backend": {
+          name: "@checkstack/queue-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "queue-memory" },
+        },
+        "@checkstack/cache-memory-backend": {
+          name: "@checkstack/cache-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "cache-memory" },
+        },
+      }),
+    };
+
+    const resolved = resolveCorePluginDeps({
+      pluginDir: ROOT,
+      readFile: readFileFromFs(fs),
+      resolveFrom: makeResolver(fs),
+    });
+
+    expect(resolved.map((r) => r.name).toSorted()).toEqual([
+      "@checkstack/cache-memory-backend",
+      "@checkstack/catalog-backend",
+      "@checkstack/notification-backend",
+      "@checkstack/notification-discord-backend",
+      "@checkstack/queue-memory-backend",
+    ]);
+  });
+
+  it("walks through common-type packages to find transitive backend deps", () => {
+    // Plugin → my-shared-common (type: common) → healthcheck-backend
+    // (Unusual but possible; common packages can list runtime deps.)
+    const fs: Fs = {
+      [`${ROOT}/package.json`]: JSON.stringify({
+        name: "@my-org/widget-backend",
+        dependencies: {
+          "@checkstack/widget-common": "^1.0.0",
+        },
+        checkstack: { type: "backend", pluginId: "widget" },
+      }),
+      ...makeFs({
+        "@checkstack/widget-common": {
+          name: "@checkstack/widget-common",
+          checkstack: { type: "common" },
+          dependencies: {
+            "@checkstack/healthcheck-backend": "^1.0.0",
+          },
+        },
+        "@checkstack/healthcheck-backend": {
+          name: "@checkstack/healthcheck-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "healthcheck" },
+        },
+        "@checkstack/queue-memory-backend": {
+          name: "@checkstack/queue-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "queue-memory" },
+        },
+        "@checkstack/cache-memory-backend": {
+          name: "@checkstack/cache-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "cache-memory" },
+        },
+      }),
+    };
+
+    const resolved = resolveCorePluginDeps({
+      pluginDir: ROOT,
+      readFile: readFileFromFs(fs),
+      resolveFrom: makeResolver(fs),
+    });
+
+    expect(resolved.map((r) => r.name)).toContain(
+      "@checkstack/healthcheck-backend",
+    );
+    // The common pkg itself isn't loaded as a plugin
+    expect(resolved.map((r) => r.name)).not.toContain(
+      "@checkstack/widget-common",
+    );
+  });
+
+  it("excludes the plugin under dev itself even when listed transitively", () => {
+    const fs: Fs = {
+      [`${ROOT}/package.json`]: JSON.stringify({
+        name: "@my-org/widget-backend",
+        dependencies: {
+          "@checkstack/healthcheck-backend": "^1.0.0",
+        },
+        checkstack: { type: "backend", pluginId: "widget" },
+      }),
+      ...makeFs({
+        "@checkstack/healthcheck-backend": {
+          name: "@checkstack/healthcheck-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "healthcheck" },
+          // Pretend the platform plugin pulls back into the user's plugin
+          // (this would never happen in practice, but the resolver must
+          // never try to load the plugin under dev as a sibling).
+          dependencies: {
+            "@my-org/widget-backend": "^1.0.0",
+          },
+        },
+        "@checkstack/queue-memory-backend": {
+          name: "@checkstack/queue-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "queue-memory" },
+        },
+        "@checkstack/cache-memory-backend": {
+          name: "@checkstack/cache-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "cache-memory" },
+        },
+      }),
+    };
+
+    const resolved = resolveCorePluginDeps({
+      pluginDir: ROOT,
+      readFile: readFileFromFs(fs),
+      resolveFrom: makeResolver(fs),
+    });
+    expect(resolved.map((r) => r.name)).not.toContain("@my-org/widget-backend");
+  });
+
+  it("skips queue-memory auto-include when bullmq is already in the dep graph", () => {
+    const fs: Fs = {
+      [`${ROOT}/package.json`]: JSON.stringify({
+        name: "@my-org/widget-backend",
+        dependencies: {
+          "@checkstack/queue-bullmq-backend": "^1.0.0",
+        },
+        checkstack: { type: "backend", pluginId: "widget" },
+      }),
+      ...makeFs({
+        "@checkstack/queue-bullmq-backend": {
+          name: "@checkstack/queue-bullmq-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "queue-bullmq" },
+        },
+        "@checkstack/queue-memory-backend": {
+          name: "@checkstack/queue-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "queue-memory" },
+        },
+        "@checkstack/cache-memory-backend": {
+          name: "@checkstack/cache-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "cache-memory" },
+        },
+      }),
+    };
+
+    const resolved = resolveCorePluginDeps({
+      pluginDir: ROOT,
+      readFile: readFileFromFs(fs),
+      resolveFrom: makeResolver(fs),
+    });
+    const names = resolved.map((r) => r.name);
+    expect(names).toContain("@checkstack/queue-bullmq-backend");
+    expect(names).not.toContain("@checkstack/queue-memory-backend");
+  });
+
+  it("does not include @checkstack/* frontend or tooling packages", () => {
+    const fs: Fs = {
+      [`${ROOT}/package.json`]: JSON.stringify({
+        name: "@my-org/widget-backend",
+        dependencies: {
+          "@checkstack/healthcheck-backend": "^1.0.0",
+          "@checkstack/healthcheck-frontend": "^1.0.0",
+          "@checkstack/scripts": "^0.1.0",
+        },
+        checkstack: { type: "backend", pluginId: "widget" },
+      }),
+      ...makeFs({
+        "@checkstack/healthcheck-backend": {
+          name: "@checkstack/healthcheck-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "healthcheck" },
+        },
+        "@checkstack/healthcheck-frontend": {
+          name: "@checkstack/healthcheck-frontend",
+          main: "src/index.tsx",
+          checkstack: { type: "frontend", pluginId: "healthcheck" },
+        },
+        "@checkstack/scripts": {
+          name: "@checkstack/scripts",
+          checkstack: { type: "tooling" },
+        },
+        "@checkstack/queue-memory-backend": {
+          name: "@checkstack/queue-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "queue-memory" },
+        },
+        "@checkstack/cache-memory-backend": {
+          name: "@checkstack/cache-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "cache-memory" },
+        },
+      }),
+    };
+
+    const resolved = resolveCorePluginDeps({
+      pluginDir: ROOT,
+      readFile: readFileFromFs(fs),
+      resolveFrom: makeResolver(fs),
+    });
+    const names = resolved.map((r) => r.name);
+    expect(names).toContain("@checkstack/healthcheck-backend");
+    expect(names).not.toContain("@checkstack/healthcheck-frontend");
+    expect(names).not.toContain("@checkstack/scripts");
+  });
+
+  it("silently skips a declared dep that isn't actually installed", () => {
+    const fs: Fs = {
+      [`${ROOT}/package.json`]: JSON.stringify({
+        name: "@my-org/widget-backend",
+        dependencies: {
+          "@checkstack/missing-backend": "^1.0.0",
+        },
+        checkstack: { type: "backend", pluginId: "widget" },
+      }),
+      ...makeFs({
+        "@checkstack/queue-memory-backend": {
+          name: "@checkstack/queue-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "queue-memory" },
+        },
+        "@checkstack/cache-memory-backend": {
+          name: "@checkstack/cache-memory-backend",
+          main: "src/index.ts",
+          checkstack: { type: "backend", pluginId: "cache-memory" },
+        },
+      }),
+    };
+
+    const resolved = resolveCorePluginDeps({
+      pluginDir: ROOT,
+      readFile: readFileFromFs(fs),
+      resolveFrom: makeResolver(fs),
+    });
+    expect(resolved.map((r) => r.name)).not.toContain(
+      "@checkstack/missing-backend",
+    );
+    // Auto-included providers still present — boot needs them.
+    expect(resolved.map((r) => r.name).toSorted()).toEqual([
+      "@checkstack/cache-memory-backend",
+      "@checkstack/queue-memory-backend",
+    ]);
+  });
+});

package/src/dev-deps-resolver.ts

@@ -0,0 +1,215 @@
+import path from "node:path";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+
+/**
+ * Walks the plugin's `package.json#dependencies` and returns the file paths
+ * of every `@checkstack/*` backend plugin module that should be co-loaded
+ * by the dev server.
+ *
+ * Why this exists: the dev server boots `core/backend` with
+ * `skipDiscovery: true` and a single manual plugin (the one under
+ * development). Real plugins almost always depend on platform plugins
+ * (`@checkstack/healthcheck-backend`, `@checkstack/notification-backend`,
+ * `@checkstack/catalog-backend`, …) — without those, the host plugin's
+ * `init()` calls into unregistered services and the boot deadlocks or
+ * crashes.
+ *
+ * Resolution rules:
+ *   1. Recursively walk `dependencies` (and `peerDependencies`) of the
+ *      plugin under dev.
+ *   2. Only follow packages whose name starts with `@checkstack/`.
+ *   3. Only include packages whose `package.json#checkstack.type === "backend"`.
+ *      Common-type packages provide types and are pulled in automatically
+ *      by the TS importer; frontend-type packages are loaded by the Vite
+ *      dev server, not the backend.
+ *   4. Skip the plugin under dev itself (its module path is passed
+ *      separately as the primary).
+ *   5. Auto-include `@checkstack/queue-memory-backend` +
+ *      `@checkstack/cache-memory-backend` when no other queue/cache
+ *      strategy is in the resolved set, so `coreServices.queueManager` /
+ *      `coreServices.cacheManager` have a registered strategy on boot.
+ *      These are the cheapest, zero-config providers — fine for dev.
+ *
+ * Returns absolute paths suitable for a child process to `bun run` /
+ * `import()`. Order is *not* topological — the platform's own dependency
+ * sorter inside `loadPlugins` handles that.
+ */
+
+interface PackageJson {
+  name?: string;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  checkstack?: {
+    type?: "backend" | "frontend" | "common" | "tooling";
+    pluginId?: string;
+  };
+}
+
+interface ResolvedPlugin {
+  name: string;
+  packageDir: string;
+  /** Path to import (the package.json `main` resolved to absolute). */
+  modulePath: string;
+}
+
+/**
+ * Resolve the set of backend plugins the dev server should load alongside
+ * the plugin under development.
+ *
+ * @param input.pluginDir   The plugin author's repo root (the cwd of the
+ *                          dev command).
+ * @param input.readFile    Injectable for tests; defaults to
+ *                          `fs.readFileSync`.
+ * @param input.resolveFrom Injectable for tests; defaults to Node's
+ *                          `createRequire(...).resolve(...)`.
+ */
+export function resolveCorePluginDeps({
+  pluginDir,
+  readFile = (p) => fs.readFileSync(p, "utf8"),
+  resolveFrom,
+}: {
+  pluginDir: string;
+  readFile?: (p: string) => string;
+  resolveFrom?: (from: string, request: string) => string | undefined;
+}): ResolvedPlugin[] {
+  const pluginPkgPath = path.join(pluginDir, "package.json");
+  const pluginPkg = JSON.parse(readFile(pluginPkgPath)) as PackageJson;
+  const pluginUnderDevName = pluginPkg.name;
+
+  // Default resolver uses createRequire from the plugin's package.json so
+  // node_modules lookup matches what `bun run` would do at runtime.
+  const defaultResolve =
+    resolveFrom ??
+    ((from: string, request: string): string | undefined => {
+      try {
+        const req = createRequire(from);
+        return req.resolve(request);
+      } catch {
+        return undefined;
+      }
+    });
+
+  const resolved = new Map<string, ResolvedPlugin>();
+  const queue: string[] = [];
+
+  const seedFromPkg = (pkg: PackageJson) => {
+    for (const block of [pkg.dependencies, pkg.peerDependencies]) {
+      if (!block) continue;
+      for (const dep of Object.keys(block)) {
+        if (!dep.startsWith("@checkstack/")) continue;
+        if (dep === pluginUnderDevName) continue;
+        queue.push(dep);
+      }
+    }
+  };
+
+  seedFromPkg(pluginPkg);
+
+  while (queue.length > 0) {
+    const depName = queue.shift()!;
+    if (resolved.has(depName)) continue;
+
+    // Resolve the package's package.json from the plugin dir's perspective.
+    const pkgJsonPath = defaultResolve(
+      path.join(pluginDir, "package.json"),
+      `${depName}/package.json`,
+    );
+    if (!pkgJsonPath) {
+      // Dep declared but not actually installed — surface during boot,
+      // not here. The `loadPlugins` import will throw with a clear msg.
+      continue;
+    }
+
+    const pkg = JSON.parse(readFile(pkgJsonPath)) as PackageJson;
+
+    // Only enqueue further deps once we've decided to (or not to) load
+    // this package — but always walk the graph. A common-type package
+    // can transitively depend on a backend-type package.
+    seedFromPkg(pkg);
+
+    if (pkg.checkstack?.type !== "backend") continue;
+
+    const packageDir = path.dirname(pkgJsonPath);
+    const main = readMain(pkg, pkgJsonPath, readFile);
+    const modulePath = path.resolve(packageDir, main);
+
+    resolved.set(depName, {
+      name: depName,
+      packageDir,
+      modulePath,
+    });
+  }
+
+  // Auto-include in-memory queue + cache providers if no provider was
+  // already pulled in via the dep graph. These are the dev-mode defaults
+  // — operators wire BullMQ / Redis in production.
+  ensureProvider({
+    needle: "queue-memory-backend",
+    siblings: ["queue-bullmq-backend"],
+    resolved,
+    pluginDir,
+    readFile,
+    resolveFrom: defaultResolve,
+  });
+  ensureProvider({
+    needle: "cache-memory-backend",
+    siblings: [], // no other cache provider exists yet
+    resolved,
+    pluginDir,
+    readFile,
+    resolveFrom: defaultResolve,
+  });
+
+  return [...resolved.values()];
+}
+
+function readMain(
+  pkg: PackageJson,
+  pkgJsonPath: string,
+  readFile: (p: string) => string,
+): string {
+  const raw = JSON.parse(readFile(pkgJsonPath)) as { main?: string };
+  return raw.main ?? "src/index.ts";
+}
+
+/**
+ * If none of `siblings` is already in the resolved set, attempt to add
+ * `needle` (a known in-memory dev provider). Silently no-op if `needle`
+ * isn't installed — operators may have a different provider wired up.
+ */
+function ensureProvider({
+  needle,
+  siblings,
+  resolved,
+  pluginDir,
+  readFile,
+  resolveFrom,
+}: {
+  needle: string;
+  siblings: string[];
+  resolved: Map<string, ResolvedPlugin>;
+  pluginDir: string;
+  readFile: (p: string) => string;
+  resolveFrom: (from: string, request: string) => string | undefined;
+}): void {
+  const fqNeedle = `@checkstack/${needle}`;
+  if (resolved.has(fqNeedle)) return;
+  for (const sibling of siblings) {
+    if (resolved.has(`@checkstack/${sibling}`)) return;
+  }
+  const pkgJsonPath = resolveFrom(
+    path.join(pluginDir, "package.json"),
+    `${fqNeedle}/package.json`,
+  );
+  if (!pkgJsonPath) return;
+  const pkg = JSON.parse(readFile(pkgJsonPath)) as PackageJson;
+  if (pkg.checkstack?.type !== "backend") return;
+  const packageDir = path.dirname(pkgJsonPath);
+  const main = readMain(pkg, pkgJsonPath, readFile);
+  resolved.set(fqNeedle, {
+    name: fqNeedle,
+    packageDir,
+    modulePath: path.resolve(packageDir, main),
+  });
+}