@checkstack/dev-server 1.0.2 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/dev-server",
-  "version": "1.0.2",
+  "version": "2.1.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",
@@ -24,9 +24,9 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.10.0",
-    "@vitejs/plugin-react": "^6.0.1",
-    "vite": "^8.0.12"
+    "@checkstack/common": "0.12.0",
+    "@vitejs/plugin-react": "^6.0.2",
+    "vite": "^8.0.16"
   },
   "peerDependencies": {
     "@checkstack/backend": "*",
@@ -42,9 +42,9 @@
   },
   "devDependencies": {
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.2",
-    "@checkstack/backend": "0.10.2",
-    "@checkstack/frontend": "0.6.3",
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/backend": "0.15.0",
+    "@checkstack/frontend": "0.6.7",
     "typescript": "^5.0.0"
   }
 }

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

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "bun:test";
+import path from "node:path";
+import { buildDevTailwindContent } from "./dev-frontend-css";
+
+const FRONTEND = "/nm/@checkstack/frontend";
+const SRC_GLOB = "**/*.{js,ts,jsx,tsx}";
+
+describe("buildDevTailwindContent", () => {
+  it("always covers the dev shell (frontend index.html + src)", () => {
+    const globs = buildDevTailwindContent({
+      frontendDir: FRONTEND,
+      pluginCwd: "/ws/packages/widget-backend",
+      pluginEntry: "/ws/packages/widget-frontend/src/index.tsx",
+    });
+    expect(globs).toContain(path.join(FRONTEND, "index.html"));
+    expect(globs).toContain(path.join(FRONTEND, "src", SRC_GLOB));
+  });
+
+  it("includes the plugin's own sources (so custom classes compile)", () => {
+    const pluginCwd = "/ws/packages/widget-backend";
+    const pluginEntry = "/ws/packages/widget-frontend/src/index.tsx";
+    const globs = buildDevTailwindContent({
+      frontendDir: FRONTEND,
+      pluginCwd,
+      pluginEntry,
+    });
+    // The directory the entry lives in (a -frontend sibling) is scanned, so
+    // an author's custom utility classes in those .tsx files compile.
+    expect(globs).toContain(
+      path.join("/ws/packages/widget-frontend/src", SRC_GLOB),
+    );
+    // The dev cwd's own src is also scanned (covers the type === "frontend"
+    // case where cwd IS the frontend package).
+    expect(globs).toContain(path.join(pluginCwd, "src", SRC_GLOB));
+  });
+
+  it("scans the cwd's own src when the plugin IS a -frontend package", () => {
+    const cwd = "/ws/packages/widget-frontend";
+    const globs = buildDevTailwindContent({
+      frontendDir: FRONTEND,
+      pluginCwd: cwd,
+      pluginEntry: path.join(cwd, "src/index.tsx"),
+    });
+    expect(globs).toContain(path.join(cwd, "src", SRC_GLOB));
+  });
+
+  it("appends extra source dirs (e.g. @checkstack/ui) when provided", () => {
+    const globs = buildDevTailwindContent({
+      frontendDir: FRONTEND,
+      pluginCwd: "/ws/p/widget-backend",
+      pluginEntry: "/ws/p/widget-frontend/src/index.tsx",
+      extraSourceDirs: ["/nm/@checkstack/ui/src", "/nm/@checkstack/foo/src"],
+    });
+    expect(globs).toContain(path.join("/nm/@checkstack/ui/src", SRC_GLOB));
+    expect(globs).toContain(path.join("/nm/@checkstack/foo/src", SRC_GLOB));
+  });
+
+  it("de-duplicates overlapping globs (cwd === entry package)", () => {
+    const cwd = "/ws/packages/widget-frontend";
+    const globs = buildDevTailwindContent({
+      frontendDir: FRONTEND,
+      pluginCwd: cwd,
+      // entry directly under cwd/src → entry dir scan and cwd/src scan coincide
+      pluginEntry: path.join(cwd, "src/index.tsx"),
+    });
+    const cwdSrcGlob = path.join(cwd, "src", SRC_GLOB);
+    expect(globs.filter((g) => g === cwdSrcGlob)).toHaveLength(1);
+    // No duplicates anywhere.
+    expect(new Set(globs).size).toBe(globs.length);
+  });
+});

package/src/dev-frontend-css.ts

@@ -0,0 +1,72 @@
+/**
+ * Tailwind content-glob assembly for the standalone dev server's inline
+ * Vite/PostCSS pipeline.
+ *
+ * The dev server roots Vite at the installed `@checkstack/frontend`
+ * directory and applies the shared `@checkstack/frontend/tailwind-preset`
+ * (theme + `tailwindcss-animate`). The preset carries NO `content`, so we
+ * supply an explicit, ABSOLUTE content-glob set here. The load-bearing
+ * part is that it reaches the plugin under development's OWN source tree —
+ * otherwise a plugin author's custom Tailwind utility classes (anything
+ * outside the precompiled `@checkstack/ui` components) never compile into
+ * the dev CSS. We also cover the dev shell and any extra source dirs (e.g.
+ * the shared UI library) so their classes generate too.
+ *
+ * Pure: takes only resolved directory inputs and returns globs. No FS, no
+ * Tailwind, no Vite — so the unit suite can assert the glob shape without
+ * touching disk.
+ */
+import path from "node:path";
+
+export interface DevTailwindContentInput {
+  /** Installed `@checkstack/frontend` root (Vite `root`). */
+  frontendDir: string;
+  /** The plugin author's package directory (the dev `cwd`). */
+  pluginCwd: string;
+  /**
+   * Absolute path to the plugin's resolved frontend entry file (from
+   * `pickFrontendEntry`). Its package directory is scanned so the author's
+   * classes are picked up even when the entry lives in a `-frontend`
+   * sibling rather than `pluginCwd` itself.
+   */
+  pluginEntry: string;
+  /**
+   * Resolved `src` directories of additional frontend packages whose
+   * components the dev shell renders (e.g. `@checkstack/ui`). Best-effort:
+   * callers pass whatever resolved cleanly; missing ones are omitted.
+   */
+  extraSourceDirs?: string[];
+}
+
+const SOURCE_GLOB = "**/*.{js,ts,jsx,tsx}";
+
+/**
+ * Build the absolute Tailwind `content` glob list for the dev pipeline.
+ * De-duplicated; order is dev-shell first, then extras, then the plugin's
+ * own sources (which are the whole point of this function).
+ */
+export function buildDevTailwindContent({
+  frontendDir,
+  pluginCwd,
+  pluginEntry,
+  extraSourceDirs = [],
+}: DevTailwindContentInput): string[] {
+  const globs: string[] = [
+    // Dev shell.
+    path.join(frontendDir, "index.html"),
+    path.join(frontendDir, "src", SOURCE_GLOB),
+    // Extra source dirs (e.g. @checkstack/ui).
+    ...extraSourceDirs.map((dir) => path.join(dir, SOURCE_GLOB)),
+    // The plugin's own sources — the load-bearing part. Cover the directory
+    // the entry file lives in (the `-frontend` package, possibly a sibling:
+    // e.g. `packages/widget-frontend/src/index.tsx` → scan that whole `src`
+    // tree) and the dev `cwd`'s own `src` (they differ for a bundle
+    // primary, and we want the author's classes whichever one holds the
+    // components).
+    path.join(path.dirname(pluginEntry), SOURCE_GLOB),
+    path.join(pluginCwd, "src", SOURCE_GLOB),
+  ];
+
+  // De-dupe while preserving order.
+  return [...new Set(globs)];
+}

package/src/dev-frontend.test.ts

@@ -1,6 +1,10 @@
 import { describe, it, expect } from "bun:test";
 import path from "node:path";
-import { pickFrontendEntry } from "./dev-frontend";
+import {
+  pickFrontendEntry,
+  resolveFromCandidates,
+  findSiblingPackageDir,
+} from "./dev-frontend";
 
 const ROOT = "/plugin-author/repo";
 
@@ -145,4 +149,125 @@ describe("pickFrontendEntry", () => {
     });
     expect(entry).toBe("/nm/@my-org/widget-frontend/src/index.tsx");
   });
+
+  it("falls back to a filesystem-sibling scan when node_modules resolution misses (standalone workspace)", () => {
+    // Mirrors the standalone scaffold: backend at packages/widget-backend,
+    // frontend at packages/widget-frontend — the latter only referenced via
+    // checkstack.bundle, never installed as a dependency, so require.resolve
+    // can never find it. The dev server must still pick it up.
+    const pluginCwd = "/ws/packages/widget-backend";
+    const entry = pickFrontendEntry({
+      pluginCwd,
+      pluginPkg: {
+        main: "src/index.ts",
+        checkstack: {
+          type: "backend",
+          bundle: ["@scope/widget-common", "@scope/widget-frontend"],
+        },
+      },
+      // node_modules resolution always misses for the workspace sibling.
+      resolveFrom: () => undefined,
+      findSiblingDir: (name) =>
+        name === "@scope/widget-frontend"
+          ? "/ws/packages/widget-frontend/package.json"
+          : undefined,
+      readFile: () => JSON.stringify({ main: "src/index.tsx" }),
+    });
+    expect(entry).toBe("/ws/packages/widget-frontend/src/index.tsx");
+  });
+
+  it("prefers node_modules resolution over the sibling-dir scan", () => {
+    let scanned = false;
+    const entry = pickFrontendEntry({
+      pluginCwd: ROOT,
+      pluginPkg: {
+        checkstack: { type: "backend", bundle: ["@my-org/widget-frontend"] },
+      },
+      resolveFrom: () => "/nm/@my-org/widget-frontend/package.json",
+      findSiblingDir: () => {
+        scanned = true;
+        return undefined;
+      },
+      readFile: () => JSON.stringify({ main: "src/index.tsx" }),
+    });
+    expect(entry).toBe("/nm/@my-org/widget-frontend/src/index.tsx");
+    expect(scanned).toBe(false);
+  });
+});
+
+describe("resolveFromCandidates", () => {
+  it("returns undefined for an unresolvable request without throwing", () => {
+    // The load-bearing behaviour for #251 bug 2: a missing module must NOT
+    // surface a (non-Error) throw to the caller. A real bun/node resolve of
+    // a guaranteed-absent specifier exercises the actual throw path.
+    const result = resolveFromCandidates({
+      request: "@checkstack/definitely-not-a-real-package-251/package.json",
+      candidateBasePaths: ["/no/such/base", process.cwd()],
+    });
+    expect(result).toBeUndefined();
+  });
+
+  it("resolves a real package from the cwd candidate", () => {
+    const result = resolveFromCandidates({
+      request: "vite/package.json",
+      candidateBasePaths: [import.meta.dir],
+    });
+    expect(result).toBeDefined();
+    expect(result).toContain("vite");
+  });
+});
+
+describe("findSiblingPackageDir", () => {
+  const PLUGIN = "/ws/packages/widget-backend";
+
+  it("finds the sibling package.json by matching its name", () => {
+    const found = findSiblingPackageDir({
+      pluginCwd: PLUGIN,
+      siblingName: "@scope/widget-frontend",
+      listDir: (dir) => {
+        expect(dir).toBe("/ws/packages");
+        return ["widget-backend", "widget-common", "widget-frontend"];
+      },
+      readFile: (p) =>
+        JSON.stringify({
+          name: `@scope/${path.basename(path.dirname(p))}`,
+        }),
+    });
+    expect(found).toBe("/ws/packages/widget-frontend/package.json");
+  });
+
+  it("returns undefined when no sibling matches", () => {
+    const found = findSiblingPackageDir({
+      pluginCwd: PLUGIN,
+      siblingName: "@scope/widget-frontend",
+      listDir: () => ["widget-backend", "widget-common"],
+      readFile: (p) =>
+        JSON.stringify({ name: `@scope/${path.basename(path.dirname(p))}` }),
+    });
+    expect(found).toBeUndefined();
+  });
+
+  it("skips entries with unreadable or malformed package.json", () => {
+    const found = findSiblingPackageDir({
+      pluginCwd: PLUGIN,
+      siblingName: "@scope/widget-frontend",
+      listDir: () => ["broken", "widget-frontend"],
+      readFile: (p) => {
+        if (p.includes("broken")) throw new Error("ENOENT");
+        return JSON.stringify({ name: "@scope/widget-frontend" });
+      },
+    });
+    expect(found).toBe("/ws/packages/widget-frontend/package.json");
+  });
+
+  it("returns undefined when the parent directory cannot be listed", () => {
+    const found = findSiblingPackageDir({
+      pluginCwd: PLUGIN,
+      siblingName: "@scope/widget-frontend",
+      listDir: () => {
+        throw new Error("ENOENT");
+      },
+    });
+    expect(found).toBeUndefined();
+  });
 });

package/src/dev-frontend.ts

@@ -10,8 +10,50 @@
  */
 import path from "node:path";
 import fs from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import type { ViteDevServer } from "vite";
+import { buildDevTailwindContent } from "./dev-frontend-css";
+
+/**
+ * Directory of THIS module (`@checkstack/dev-server`'s installed location).
+ * `@checkstack/frontend`, `vite`, and `@vitejs/plugin-react` are
+ * dev-server's own (peer/runtime) dependencies, so under a published
+ * `bun install` layout they are reachable from here even though they are
+ * NOT reachable from the plugin author's package — the plugin only
+ * declares `@checkstack/dev-server`, never `@checkstack/frontend` or Vite
+ * directly. See {@link resolveFromCandidates}.
+ */
+const DEV_SERVER_MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve a package request from the FIRST base path under which it is
+ * reachable, returning the resolved path or `undefined`.
+ *
+ * Bun's `createRequire(...).resolve()` throws a value that is NOT an
+ * `instanceof Error` for an unresolvable specifier (a `ResolveError`-like
+ * object), so a bare `try/catch` that rethrows leaks a non-Error up the
+ * stack — which is exactly why the caller's `extractErrorMessage` used to
+ * print the useless `"An error occurred"` fallback. We swallow the throw
+ * per-candidate here and let the caller decide what to do with a clean
+ * `undefined`.
+ */
+export function resolveFromCandidates({
+  request,
+  candidateBasePaths,
+}: {
+  request: string;
+  candidateBasePaths: string[];
+}): string | undefined {
+  for (const base of candidateBasePaths) {
+    try {
+      return createRequire(path.join(base, "package.json")).resolve(request);
+    } catch {
+      // not reachable from this base — try the next
+    }
+  }
+  return undefined;
+}
 
 // `vite` and `@vitejs/plugin-react` are lazily imported inside
 // `startFrontendDevServer` so that consumers of this module which only
@@ -44,11 +86,24 @@ export async function startFrontendDevServer({
   ]);
   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");
+  // Resolve the @checkstack/frontend package. In the monorepo it is
+  // reachable from the plugin's own package; under a PUBLISHED
+  // `bun install`, the plugin only depends on @checkstack/dev-server, so
+  // @checkstack/frontend (dev-server's peer dep) is reachable from THIS
+  // module's install location, not the plugin's. Try the plugin first so a
+  // plugin that pins its own @checkstack/frontend wins, then fall back to
+  // dev-server's location. (Before this fallback, the resolve threw a
+  // non-Error under Bun and the dev server logged "An error occurred" and
+  // ran backend-only — #251 bug 2.)
+  const frontendPkgJsonPath = resolveFromCandidates({
+    request: "@checkstack/frontend/package.json",
+    candidateBasePaths: [pluginCwd, DEV_SERVER_MODULE_DIR],
+  });
+  if (!frontendPkgJsonPath) {
+    throw new Error(
+      "Could not resolve @checkstack/frontend. It ships as a dependency of @checkstack/dev-server; ensure your plugin's dev dependencies are installed (`bun install`).",
+    );
+  }
   const frontendDir = path.dirname(frontendPkgJsonPath);
   const indexHtmlPath = path.join(frontendDir, "index.html");
   if (!fs.existsSync(indexHtmlPath)) {
@@ -59,23 +114,30 @@ export async function startFrontendDevServer({
 
   // Resolve the plugin under dev's main entry — Vite's alias maps the
   // virtual import `virtual:checkstack-dev-plugin` to this file.
+  // Cast: `JSON.parse` is typed `any`; we read only these optional fields
+  // and every consumer treats them as optional, so an unexpected shape
+  // narrows to `undefined` rather than crashing.
   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.
+  // listed in `checkstack.bundle`. We resolve the sibling from the plugin
+  // first, then from dev-server's location (published layout), and finally
+  // fall back to scanning sibling directories — a standalone workspace's
+  // own `-frontend` package lives at `packages/<base>-frontend` and is NOT
+  // a node_modules entry (nothing depends on it as an npm package; it is
+  // only referenced via `checkstack.bundle`), so `require.resolve` can
+  // never find it. See {@link findSiblingPackageDir}.
   const pluginEntry = pickFrontendEntry({
     pluginCwd,
     pluginPkg,
-    resolveFrom: (request) => {
-      try {
-        return req.resolve(request);
-      } catch {
-        return;
-      }
-    },
+    resolveFrom: (request) =>
+      resolveFromCandidates({
+        request,
+        candidateBasePaths: [pluginCwd, DEV_SERVER_MODULE_DIR],
+      }),
   });
   if (!pluginEntry) {
     throw new Error(
@@ -83,6 +145,19 @@ export async function startFrontendDevServer({
     );
   }
 
+  // Build the Tailwind/PostCSS pipeline for the dev shell. `@checkstack/
+  // frontend` now ships the Tailwind toolchain as RUNTIME deps and exports
+  // a `tailwind-preset` subpath, so we can assemble the pipeline from a
+  // published install. The key win over the frontend's own config: we
+  // inject the plugin under development's source globs into `content`, so a
+  // plugin author's custom utility classes compile in dev. Returns
+  // `undefined` (→ Vite default PostCSS) if the toolchain can't be loaded.
+  const postcssPlugins = await loadDevPostcssPlugins({
+    frontendDir,
+    pluginCwd,
+    pluginEntry,
+  });
+
   const server = await createViteServer({
     root: frontendDir,
     configFile: false, // we control the config inline
@@ -98,6 +173,11 @@ export async function startFrontendDevServer({
         "/assets/plugins": { target: backendUrl, changeOrigin: true },
       },
     },
+    // Explicit PostCSS chain (Tailwind preset + plugin globs + autoprefixer)
+    // when it could be assembled — overrides Vite's auto-discovery of the
+    // frontend's own `postcss.config.js`, whose Tailwind `content` globs are
+    // relative to the dev cwd and never reach the plugin under development.
+    ...(postcssPlugins ? { css: { postcss: { plugins: postcssPlugins } } } : {}),
     // 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`,
@@ -134,13 +214,163 @@ export async function startFrontendDevServer({
   return server;
 }
 
+/**
+ * The Vite config types `css.postcss` as a `string | (ProcessOptions & {
+ * plugins?: PostCSS.AcceptedPlugin[] })`. We pull the plugin element type
+ * straight out of that shape so the helper stays free of `any` without
+ * depending on the `postcss` types package directly (we only depend on
+ * `vite`, which re-exposes them).
+ */
+type ViteCss = NonNullable<import("vite").UserConfig["css"]>;
+type ViteCssPostcssObject = Extract<ViteCss["postcss"], { plugins?: unknown }>;
+type PostcssPlugin = NonNullable<ViteCssPostcssObject["plugins"]>[number];
+
+/** The fields we read off `@checkstack/frontend`'s tailwind preset. */
+interface TailwindPreset {
+  [key: string]: unknown;
+}
+
+/**
+ * Assemble the dev PostCSS plugin chain — the shared `@checkstack/frontend`
+ * Tailwind preset (theme + `tailwindcss-animate`) with a `content` glob set
+ * that reaches the plugin author's OWN sources, plus autoprefixer.
+ *
+ * Returns `undefined` when the chain cannot be built (e.g. an older
+ * `@checkstack/frontend` without the preset/toolchain, or `tailwindcss` not
+ * resolvable). In that case the caller falls back to Vite's default PostCSS
+ * auto-discovery — the dev server still starts. This mirrors the rest of
+ * this module: a CSS-pipeline hiccup must never take the dev server down.
+ */
+async function loadDevPostcssPlugins({
+  frontendDir,
+  pluginCwd,
+  pluginEntry,
+}: {
+  frontendDir: string;
+  pluginCwd: string;
+  pluginEntry: string;
+}): Promise<PostcssPlugin[] | undefined> {
+  try {
+    // `tailwindcss` + `autoprefixer` ship as `@checkstack/frontend`'s
+    // RUNTIME deps, so they are reachable from the frontend root in any
+    // layout (monorepo or published install).
+    const frontendRequire = createRequire(
+      path.join(frontendDir, "package.json"),
+    );
+    const tailwindModule = await import(
+      pathToFileURL(frontendRequire.resolve("tailwindcss")).href
+    );
+    const autoprefixerModule = await import(
+      pathToFileURL(frontendRequire.resolve("autoprefixer")).href
+    );
+    // Cast: dynamic `import()` of CJS/ESM packages is typed `any` for the
+    // namespace, so `.default` is untyped. `tailwindcss` and `autoprefixer`
+    // are the canonical PostCSS-plugin factories; we assert the call
+    // signatures we actually use. A wrong-shaped module is caught by the
+    // surrounding try/catch (falls back to Vite's default PostCSS).
+    const tailwindcss = tailwindModule.default as (
+      config: TailwindPreset & { content: string[] },
+    ) => PostcssPlugin;
+    const autoprefixer = autoprefixerModule.default as () => PostcssPlugin;
+
+    // The shared theme + tailwindcss-animate, exported as a public subpath
+    // so we don't reach into frontend internals. It carries no `content`.
+    const presetPath = frontendRequire.resolve(
+      "@checkstack/frontend/tailwind-preset",
+    );
+    const presetModule = await import(pathToFileURL(presetPath).href);
+    // Cast: the preset is a JS module typed `any`; we spread it into the
+    // tailwind config and only add `content`, so the loose shape suffices.
+    const preset = (presetModule.default ?? presetModule) as TailwindPreset;
+
+    // Best-effort: include the shared UI library so its source classes (the
+    // dev shell renders `@checkstack/ui` components) compile too. Its
+    // resolved package dir is `<pkg>/src`.
+    const extraSourceDirs: string[] = [];
+    const uiPkgJson = resolveFromCandidates({
+      request: "@checkstack/ui/package.json",
+      candidateBasePaths: [frontendDir, pluginCwd, DEV_SERVER_MODULE_DIR],
+    });
+    if (uiPkgJson) {
+      extraSourceDirs.push(path.join(path.dirname(uiPkgJson), "src"));
+    }
+
+    const content = buildDevTailwindContent({
+      frontendDir,
+      pluginCwd,
+      pluginEntry,
+      extraSourceDirs,
+    });
+
+    return [tailwindcss({ ...preset, content }), autoprefixer()];
+  } catch {
+    // Any failure → fall back to Vite's default PostCSS discovery.
+    return undefined;
+  }
+}
+
+/**
+ * Find the `package.json` of a bundle sibling that lives as a FILESYSTEM
+ * sibling of the plugin (not a node_modules entry).
+ *
+ * A standalone scaffold lays the trio out as `packages/<base>-common`,
+ * `packages/<base>-backend`, `packages/<base>-frontend`. The `-frontend`
+ * package is referenced only via `checkstack.bundle` — nothing `depends`
+ * on it as an npm package — so bun never links it into any
+ * `node_modules`, and `require.resolve("@scope/<base>-frontend")` cannot
+ * find it from anywhere. We instead scan the directories next to the
+ * plugin's own directory for one whose `package.json#name` matches.
+ *
+ * Pure: every FS touch is injected so the unit suite can drive it without
+ * disk.
+ */
+export function findSiblingPackageDir({
+  pluginCwd,
+  siblingName,
+  listDir = (dir) =>
+    fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name),
+  readFile = (p) => fs.readFileSync(p, "utf8"),
+}: {
+  pluginCwd: string;
+  siblingName: string;
+  /** List the immediate subdirectory names of a directory. */
+  listDir?: (dir: string) => string[];
+  readFile?: (p: string) => string;
+}): string | undefined {
+  const parent = path.dirname(pluginCwd);
+  let entries: string[];
+  try {
+    entries = listDir(parent);
+  } catch {
+    return undefined;
+  }
+  for (const name of entries) {
+    const candidate = path.join(parent, name, "package.json");
+    try {
+      // Cast: `JSON.parse` is typed `any`; we only compare the optional
+      // `name` string. A malformed/unexpected shape simply won't match.
+      const pkg = JSON.parse(readFile(candidate)) as { name?: string };
+      if (pkg.name === siblingName) return candidate;
+    } catch {
+      // not a package dir, unreadable, or malformed — skip
+    }
+  }
+  return undefined;
+}
+
 /**
  * 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.
+ *     listing a `-frontend` sibling): the sibling's `main`. Resolved
+ *     through node_modules when the sibling is an installed package, or —
+ *     for a standalone workspace where the sibling is only a filesystem
+ *     neighbour — by scanning sibling directories (see
+ *     {@link findSiblingPackageDir}).
  *
  * Pure: all FS lookups go through injected hooks so the test suite can
  * drive every branch without touching disk.
@@ -149,6 +379,7 @@ export function pickFrontendEntry({
   pluginCwd,
   pluginPkg,
   resolveFrom,
+  findSiblingDir,
   readFile = (p) => fs.readFileSync(p, "utf8"),
 }: {
   pluginCwd: string;
@@ -162,6 +393,12 @@ export function pickFrontendEntry({
    * runtime.
    */
   resolveFrom?: (request: string) => string | undefined;
+  /**
+   * Optional injection: locate a bundle sibling that lives as a filesystem
+   * neighbour rather than a node_modules entry. Defaults to
+   * {@link findSiblingPackageDir} rooted at the plugin's directory.
+   */
+  findSiblingDir?: (siblingName: string) => string | undefined;
   readFile?: (p: string) => string;
 }): string | undefined {
   if (pluginPkg.checkstack?.type === "frontend") {
@@ -179,12 +416,22 @@ export function pickFrontendEntry({
         return undefined;
       }
     });
+  const siblingDirFinder =
+    findSiblingDir ??
+    ((siblingName: string): string | undefined =>
+      findSiblingPackageDir({ pluginCwd, siblingName, readFile }));
   const siblings = pluginPkg.checkstack?.bundle ?? [];
   for (const sibling of siblings) {
     if (!sibling.endsWith("-frontend")) continue;
-    const pkgJsonPath = resolver(`${sibling}/package.json`);
+    // node_modules resolution first (monorepo / installed sibling), then a
+    // filesystem-neighbour scan (standalone workspace whose -frontend is a
+    // sibling package, not a dependency).
+    const pkgJsonPath =
+      resolver(`${sibling}/package.json`) ?? siblingDirFinder(sibling);
     if (!pkgJsonPath) continue;
     try {
+      // Cast: `JSON.parse` is typed `any`; we read only the optional
+      // `main` field and default it when absent.
       const pkg = JSON.parse(readFile(pkgJsonPath)) as { main?: string };
       return path.resolve(
         path.dirname(pkgJsonPath),

package/src/dev-server.ts

@@ -165,7 +165,7 @@ export async function runDevServer(rawArgs: string[]): Promise<number> {
 }
 
 function printHelp(): void {
-  console.log(String.raw`Usage: checkstack-scripts dev [options]
+  console.log(String.raw`Usage: checkstack-dev [options]
 
 Spins up a local Checkstack dev server with the current directory's
 plugin loaded. Same boot code as production — the only differences are:
@@ -173,6 +173,10 @@ plugin loaded. Same boot code as production — the only differences are:
   * a synthetic dev auth grants every access rule (no login)
   * the backend restarts on changes under ./src
 
+This binary ships in the @checkstack/dev-server package. Add it as a
+devDependency and wire "dev": "checkstack-dev" in your package.json, or
+run it directly via: bunx @checkstack/dev-server
+
 Options:
   --cwd <dir>             Plugin directory (default: process.cwd())
   --port <num>            Backend HTTP port (default: 3000 or $PORT)