@checkstack/scripts 0.1.1 → 0.2.0

package/src/commands/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),
+  });
+}

package/src/commands/dev-frontend.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from "bun:test";
+import path from "node:path";
+import { pickFrontendEntry } from "./dev-frontend";
+
+const ROOT = "/plugin-author/repo";
+
+describe("pickFrontendEntry", () => {
+  it("returns <cwd>/<main> when the cwd is itself a -frontend plugin", () => {
+    const entry = pickFrontendEntry({
+      pluginCwd: ROOT,
+      pluginPkg: {
+        main: "src/index.tsx",
+        checkstack: { type: "frontend" },
+      },
+    });
+    expect(entry).toBe(path.resolve(ROOT, "src/index.tsx"));
+  });
+
+  it("falls back to src/index.tsx when no main field on a -frontend plugin", () => {
+    const entry = pickFrontendEntry({
+      pluginCwd: ROOT,
+      pluginPkg: { checkstack: { type: "frontend" } },
+    });
+    expect(entry).toBe(path.resolve(ROOT, "src/index.tsx"));
+  });
+
+  it("resolves a -frontend sibling's main when called from a bundle primary", () => {
+    const siblingPkgPath =
+      "/plugin-author/repo/node_modules/@my-org/widget-frontend/package.json";
+    const entry = pickFrontendEntry({
+      pluginCwd: ROOT,
+      pluginPkg: {
+        main: "src/index.ts",
+        checkstack: {
+          type: "backend",
+          bundle: ["@my-org/widget-common", "@my-org/widget-frontend"],
+        },
+      },
+      resolveFrom: (request) =>
+        request === "@my-org/widget-frontend/package.json"
+          ? siblingPkgPath
+          : undefined,
+      readFile: () =>
+        JSON.stringify({
+          name: "@my-org/widget-frontend",
+          main: "dist/index.js",
+        }),
+    });
+    expect(entry).toBe(
+      "/plugin-author/repo/node_modules/@my-org/widget-frontend/dist/index.js",
+    );
+  });
+
+  it("skips non-frontend siblings in the bundle list", () => {
+    let resolveCalls = 0;
+    const entry = pickFrontendEntry({
+      pluginCwd: ROOT,
+      pluginPkg: {
+        checkstack: {
+          type: "backend",
+          // Only -common siblings — no -frontend
+          bundle: ["@my-org/widget-common", "@my-org/widget-other"],
+        },
+      },
+      resolveFrom: () => {
+        resolveCalls++;
+        return "/never";
+      },
+    });
+    expect(entry).toBeUndefined();
+    expect(resolveCalls).toBe(0); // didn't even attempt a resolve
+  });
+
+  it("returns undefined when the named -frontend sibling is not installed", () => {
+    const entry = pickFrontendEntry({
+      pluginCwd: ROOT,
+      pluginPkg: {
+        checkstack: {
+          type: "backend",
+          bundle: ["@my-org/widget-frontend"],
+        },
+      },
+      resolveFrom: () => undefined,
+    });
+    expect(entry).toBeUndefined();
+  });
+
+  it("tries the next -frontend sibling when the first is malformed", () => {
+    let resolveCalls = 0;
+    const fs: Record<string, string> = {
+      "/nm/@my-org/first-frontend/package.json": "not-json",
+      "/nm/@my-org/second-frontend/package.json": JSON.stringify({
+        main: "src/index.tsx",
+      }),
+    };
+    const entry = pickFrontendEntry({
+      pluginCwd: ROOT,
+      pluginPkg: {
+        checkstack: {
+          type: "backend",
+          bundle: [
+            "@my-org/first-frontend",
+            "@my-org/second-frontend",
+          ],
+        },
+      },
+      resolveFrom: (request) => {
+        resolveCalls++;
+        if (request === "@my-org/first-frontend/package.json")
+          return "/nm/@my-org/first-frontend/package.json";
+        if (request === "@my-org/second-frontend/package.json")
+          return "/nm/@my-org/second-frontend/package.json";
+        return undefined;
+      },
+      readFile: (p) => {
+        const content = fs[p];
+        if (content === undefined) throw new Error(`ENOENT: ${p}`);
+        return content;
+      },
+    });
+    expect(entry).toBe("/nm/@my-org/second-frontend/src/index.tsx");
+    // Exactly one attempt per sibling
+    expect(resolveCalls).toBe(2);
+  });
+
+  it("returns undefined for a backend plugin with no bundle siblings at all", () => {
+    const entry = pickFrontendEntry({
+      pluginCwd: ROOT,
+      pluginPkg: { checkstack: { type: "backend" } },
+    });
+    expect(entry).toBeUndefined();
+  });
+
+  it("falls back to src/index.tsx for a sibling without a main field", () => {
+    const entry = pickFrontendEntry({
+      pluginCwd: ROOT,
+      pluginPkg: {
+        checkstack: {
+          type: "backend",
+          bundle: ["@my-org/widget-frontend"],
+        },
+      },
+      resolveFrom: () => "/nm/@my-org/widget-frontend/package.json",
+      readFile: () => JSON.stringify({ name: "@my-org/widget-frontend" }),
+    });
+    expect(entry).toBe("/nm/@my-org/widget-frontend/src/index.tsx");
+  });
+});

package/src/commands/dev-frontend.ts

@@ -0,0 +1,198 @@
+/**
+ * Spawns a Vite dev server hosting the Checkstack frontend shell with
+ * the plugin under development pre-registered via the
+ * `virtual:checkstack-dev-plugin` alias.
+ *
+ * Reuses `core/frontend`'s `App.tsx`, `dev-main.tsx`, `index.css`, and
+ * `loadPlugins()` — same code path as production. Vite proxies `/api`
+ * and `/assets/plugins` to the backend dev server (default port 3000)
+ * so the SPA can talk to the running plugin.
+ */
+import path from "node:path";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import type { ViteDevServer } from "vite";
+
+// `vite` and `@vitejs/plugin-react` are lazily imported inside
+// `startFrontendDevServer` so that consumers of this module which only
+// touch `pickFrontendEntry` (notably the unit tests) don't trigger
+// Vite's eager module init. Bun's test runner cross-mocks `fs.readFileSync`
+// in plugin-discovery.test.ts; Vite's constants.js calls `readFileSync`
+// at load time and trips that leaked mock. Lazy-importing keeps the test
+// suite isolated.
+
+interface FrontendDevOptions {
+  /** Plugin author's cwd (the package whose frontend code we're dev'ing). */
+  pluginCwd: string;
+  /** HTTP port for the Vite dev server. */
+  port: number;
+  /** Backend dev server URL — `/api` and `/assets/plugins` are proxied here. */
+  backendUrl: string;
+}
+
+export async function startFrontendDevServer({
+  pluginCwd,
+  port,
+  backendUrl,
+}: FrontendDevOptions): Promise<ViteDevServer> {
+  // Lazy-imported here to avoid Vite's eager module init when the dev
+  // server isn't actually being launched (e.g. unit tests that only
+  // exercise `pickFrontendEntry`).
+  const [{ createServer: createViteServer }, reactModule] = await Promise.all([
+    import("vite"),
+    import("@vitejs/plugin-react"),
+  ]);
+  const react = reactModule.default;
+
+  // Resolve the @checkstack/frontend package from the plugin author's
+  // node_modules so paths line up with what `bun install` produced. Same
+  // strategy the backend dev command uses for @checkstack/backend.
+  const req = createRequire(path.join(pluginCwd, "package.json"));
+  const frontendPkgJsonPath = req.resolve("@checkstack/frontend/package.json");
+  const frontendDir = path.dirname(frontendPkgJsonPath);
+  const indexHtmlPath = path.join(frontendDir, "index.html");
+  if (!fs.existsSync(indexHtmlPath)) {
+    throw new Error(
+      `@checkstack/frontend at ${frontendDir} has no index.html — incompatible version?`,
+    );
+  }
+
+  // Resolve the plugin under dev's main entry — Vite's alias maps the
+  // virtual import `virtual:checkstack-dev-plugin` to this file.
+  const pluginPkg = JSON.parse(
+    fs.readFileSync(path.join(pluginCwd, "package.json"), "utf8"),
+  ) as { main?: string; checkstack?: { type?: string; bundle?: string[] } };
+  // Bundle primaries point at their own backend main, but the frontend
+  // entry lives in a sibling. Best-effort: if the cwd's checkstack.type
+  // is "frontend", use cwd; else look for a sibling -frontend package
+  // listed in `checkstack.bundle` and resolve through node_modules.
+  const pluginEntry = pickFrontendEntry({
+    pluginCwd,
+    pluginPkg,
+    resolveFrom: (request) => {
+      try {
+        return req.resolve(request);
+      } catch {
+        return;
+      }
+    },
+  });
+  if (!pluginEntry) {
+    throw new Error(
+      "Could not determine the plugin's frontend entry. Either run from a `-frontend` package directly, or list a `-frontend` sibling in your primary package's `checkstack.bundle`.",
+    );
+  }
+
+  const server = await createViteServer({
+    root: frontendDir,
+    configFile: false, // we control the config inline
+    server: {
+      port,
+      strictPort: true,
+      proxy: {
+        "/api": {
+          target: backendUrl,
+          changeOrigin: true,
+          ws: true,
+        },
+        "/assets/plugins": { target: backendUrl, changeOrigin: true },
+      },
+    },
+    // Replace the production `main.tsx` entry with our `dev-main.tsx`
+    // shell. Vite will pick this up via `index.html`'s `<script>` tag,
+    // because dev-main.tsx imports `virtual:checkstack-dev-plugin`,
+    // which is aliased below to the plugin author's actual frontend
+    // entry file.
+    plugins: [
+      react(),
+      {
+        name: "checkstack-dev-entry",
+        // Replace `/src/main.tsx` references in index.html with dev-main.
+        transformIndexHtml(html: string) {
+          return html.replace("/src/main.tsx", "/src/dev-main.tsx");
+        },
+      },
+    ],
+    resolve: {
+      alias: {
+        "virtual:checkstack-dev-plugin": pluginEntry,
+      },
+    },
+    // Without this, Vite tries to optimize the dev plugin's deps and
+    // chokes on workspace-resolved peers. Letting Vite skip pre-bundle
+    // for our plugin keeps live-edit fast.
+    optimizeDeps: {
+      exclude: ["virtual:checkstack-dev-plugin"],
+    },
+  });
+
+  await server.listen();
+  const info = server.config.server;
+  console.log(
+    `🎨 Frontend dev server: http://${info.host ?? "localhost"}:${info.port ?? port}`,
+  );
+  return server;
+}
+
+/**
+ * Resolve the entry file Vite should load for the plugin's frontend.
+ *
+ *   - For a `-frontend` plugin: the cwd's own `main` field.
+ *   - For a bundle primary (e.g. `-backend` with `checkstack.bundle`
+ *     listing a `-frontend` sibling): the sibling's `main`, resolved
+ *     through node_modules.
+ *
+ * Pure: all FS lookups go through injected hooks so the test suite can
+ * drive every branch without touching disk.
+ */
+export function pickFrontendEntry({
+  pluginCwd,
+  pluginPkg,
+  resolveFrom,
+  readFile = (p) => fs.readFileSync(p, "utf8"),
+}: {
+  pluginCwd: string;
+  pluginPkg: {
+    main?: string;
+    checkstack?: { type?: string; bundle?: string[] };
+  };
+  /**
+   * Optional injection. Defaults to a `createRequire` rooted at the
+   * plugin's package.json — same resolution path as `bun run` at
+   * runtime.
+   */
+  resolveFrom?: (request: string) => string | undefined;
+  readFile?: (p: string) => string;
+}): string | undefined {
+  if (pluginPkg.checkstack?.type === "frontend") {
+    return path.resolve(pluginCwd, pluginPkg.main ?? "src/index.tsx");
+  }
+  // Bundle primary — find a `-frontend` sibling and resolve its entry.
+  const resolver =
+    resolveFrom ??
+    ((request: string): string | undefined => {
+      try {
+        return createRequire(path.join(pluginCwd, "package.json")).resolve(
+          request,
+        );
+      } catch {
+        return undefined;
+      }
+    });
+  const siblings = pluginPkg.checkstack?.bundle ?? [];
+  for (const sibling of siblings) {
+    if (!sibling.endsWith("-frontend")) continue;
+    const pkgJsonPath = resolver(`${sibling}/package.json`);
+    if (!pkgJsonPath) continue;
+    try {
+      const pkg = JSON.parse(readFile(pkgJsonPath)) as { main?: string };
+      return path.resolve(
+        path.dirname(pkgJsonPath),
+        pkg.main ?? "src/index.tsx",
+      );
+    } catch {
+      // sibling installed but malformed; try the next
+    }
+  }
+  return undefined;
+}