@checkstack/dev-server 2.1.2 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/dev-server",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "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,13 +24,14 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.14.1",
+    "@checkstack/common": "0.15.0",
     "@vitejs/plugin-react": "^6.0.2",
     "vite": "^8.0.16"
   },
   "peerDependencies": {
     "@checkstack/backend": "*",
-    "@checkstack/frontend": "*"
+    "@checkstack/frontend": "*",
+    "@checkstack/ui": "*"
   },
   "peerDependenciesMeta": {
     "@checkstack/backend": {
@@ -38,13 +39,17 @@
     },
     "@checkstack/frontend": {
       "optional": true
+    },
+    "@checkstack/ui": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.4.2",
-    "@checkstack/backend": "0.16.2",
-    "@checkstack/frontend": "0.7.2",
+    "@checkstack/scripts": "0.6.1",
+    "@checkstack/backend": "0.18.0",
+    "@checkstack/frontend": "0.9.1",
+    "@checkstack/ui": "1.15.1",
     "typescript": "^5.0.0"
   }
 }

package/src/dev-frontend.ts

@@ -10,10 +10,17 @@
  */
 import path from "node:path";
 import fs from "node:fs";
+import os from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import type { ViteDevServer } from "vite";
 import { buildDevTailwindContent } from "./dev-frontend-css";
+import {
+  prepareMonacoWorkers,
+  type MonacoWorkerSetup,
+  type ViteBuild,
+} from "./dev-monaco-workers";
+import type { MonacoViteConfig } from "@checkstack/ui/src/vite-monaco";
 
 /**
  * Directory of THIS module (`@checkstack/dev-server`'s installed location).
@@ -80,10 +87,8 @@ export async function startFrontendDevServer({
   // 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 [{ createServer: createViteServer, build }, reactModule] =
+    await Promise.all([import("vite"), import("@vitejs/plugin-react")]);
   const react = reactModule.default;
 
   // Resolve the @checkstack/frontend package. In the monorepo it is
@@ -158,6 +163,29 @@ export async function startFrontendDevServer({
     pluginEntry,
   });
 
+  // Monaco / VS Code editor Vite settings (ES-module workers + the `vscode`
+  // alias) from @checkstack/frontend's shared helper, so the dev server matches
+  // the app's config instead of drifting. Without the `vscode` alias,
+  // @checkstack/ui's CodeEditor leaks a runtime `require("vscode")` into the
+  // browser. Returns `undefined` when the editor stack isn't resolvable — the
+  // dev server still starts; the editor just isn't configured.
+  const monaco = await loadMonacoViteConfig({ frontendDir, pluginCwd });
+
+  // Pre-build @checkstack/ui's Monaco language workers and redirect its
+  // `?worker&url` imports to them. In a standalone install @checkstack/ui is a
+  // pre-bundled npm dep and Vite can't process those worker imports during
+  // pre-bundling; this serves pre-built bundles instead so the CodeEditor
+  // renders. See dev-monaco-workers.ts. `undefined` (editor degrades, dev
+  // server still starts) when the editor stack or build is unavailable.
+  const monacoWorkers = monaco
+    ? await loadMonacoWorkers({
+        frontendDir,
+        pluginCwd,
+        vscodeDir: monaco.resolve.alias.vscode,
+        buildFn: build,
+      })
+    : undefined;
+
   const server = await createViteServer({
     root: frontendDir,
     configFile: false, // we control the config inline
@@ -192,11 +220,29 @@ export async function startFrontendDevServer({
           return html.replace("/src/main.tsx", "/src/dev-main.tsx");
         },
       },
+      // Serves the pre-built Monaco worker bundles (no-op when absent).
+      ...(monacoWorkers ? [monacoWorkers.plugin] : []),
     ],
+    // ES-module worker format for the Monaco language workers (no-op when the
+    // editor stack isn't resolvable).
+    ...(monaco ? { worker: monaco.worker } : {}),
     resolve: {
-      alias: {
-        "virtual:checkstack-dev-plugin": pluginEntry,
-      },
+      // Share a single React copy between the dev shell and the plugin
+      // (including @checkstack/ui's CodeEditor) so its hooks don't hit a second
+      // React instance ("Invalid hook call"). Mirrors the app's vite.config.
+      ...(monacoWorkers
+        ? { dedupe: ["react", "react-dom", "react/jsx-runtime"] }
+        : {}),
+      alias: [
+        { find: "virtual:checkstack-dev-plugin", replacement: pluginEntry },
+        // `vscode` npm-alias → real @codingame package dir (see monacoViteConfig).
+        ...(monaco
+          ? [{ find: "vscode", replacement: monaco.resolve.alias.vscode }]
+          : []),
+        // Redirect @checkstack/ui's `?worker&url` worker imports to the
+        // pre-built bundles served by the plugin above (see dev-monaco-workers).
+        ...(monacoWorkers?.aliases ?? []),
+      ],
     },
     // Without this, Vite tries to optimize the dev plugin's deps and
     // chokes on workspace-resolved peers. Letting Vite skip pre-bundle
@@ -230,6 +276,121 @@ interface TailwindPreset {
   [key: string]: unknown;
 }
 
+/**
+ * Build the Monaco / VS Code editor Vite settings from `@checkstack/frontend`'s
+ * shared `monacoViteConfig` helper — the SAME settings the frontend's own
+ * `vite.config.ts` uses, so the dev server and the app never drift.
+ *
+ * The editor stack (`@typefox/monaco-editor-react`, `@codingame/*`) lives in
+ * `@checkstack/ui`'s dependencies, so we resolve from the plugin's installed
+ * `@checkstack/ui` location (falling back to the frontend / plugin / dev-server
+ * dirs). Returns `undefined` on any failure (e.g. `@checkstack/ui` not
+ * installed, or an editor-less plugin) — the dev server still starts; only the
+ * in-browser editor's language features are unavailable. Mirrors
+ * {@link loadDevPostcssPlugins}: a frontend-tooling hiccup never takes the dev
+ * server down.
+ */
+async function loadMonacoViteConfig({
+  frontendDir,
+  pluginCwd,
+}: {
+  frontendDir: string;
+  pluginCwd: string;
+}): Promise<MonacoViteConfig | undefined> {
+  try {
+    // Load the helper from the RESOLVED `@checkstack/ui` (a peer the plugin
+    // author installs), mirroring loadDevPostcssPlugins — never a static
+    // import, so `@checkstack/ui` stays a peer dep rather than becoming a hard
+    // runtime dependency of the dev server.
+    const helperPath = resolveFromCandidates({
+      request: "@checkstack/ui/src/vite-monaco",
+      candidateBasePaths: [frontendDir, pluginCwd, DEV_SERVER_MODULE_DIR],
+    });
+    if (!helperPath) return undefined;
+    const mod = await import(pathToFileURL(helperPath).href);
+    // Cast: dynamic `import()`'s namespace is untyped. `monacoViteConfig` is the
+    // documented export of `@checkstack/ui/src/vite-monaco`; a wrong-shaped
+    // module is caught by the surrounding try/catch (→ undefined fallback).
+    const buildConfig = mod.monacoViteConfig as (args: {
+      resolveFrom: string[];
+    }) => MonacoViteConfig;
+    return buildConfig({ resolveFrom: monacoResolveFrom({ frontendDir, pluginCwd }) });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Candidate base dirs to resolve the Monaco editor stack from. The stack
+ * (`@typefox/monaco-editor-react`, `@codingame/*`) lives in `@checkstack/ui`'s
+ * deps, so the ui package's dir comes first, falling back to the frontend /
+ * plugin / dev-server dirs.
+ */
+function monacoResolveFrom({
+  frontendDir,
+  pluginCwd,
+}: {
+  frontendDir: string;
+  pluginCwd: string;
+}): string[] {
+  const uiPkgJson = resolveFromCandidates({
+    request: "@checkstack/ui/package.json",
+    candidateBasePaths: [frontendDir, pluginCwd, DEV_SERVER_MODULE_DIR],
+  });
+  return [
+    ...(uiPkgJson ? [path.dirname(uiPkgJson)] : []),
+    frontendDir,
+    pluginCwd,
+    DEV_SERVER_MODULE_DIR,
+  ];
+}
+
+/**
+ * `node_modules/.cache` home for the pre-built Monaco workers, falling back to
+ * a tmp dir if the plugin's `node_modules` isn't writable.
+ */
+function monacoWorkerCacheDir({ pluginCwd }: { pluginCwd: string }): string {
+  const preferred = path.join(
+    pluginCwd,
+    "node_modules",
+    ".cache",
+    "checkstack-dev-monaco",
+  );
+  try {
+    fs.mkdirSync(preferred, { recursive: true });
+    return preferred;
+  } catch {
+    const fallback = path.join(os.tmpdir(), "checkstack-dev-monaco");
+    fs.mkdirSync(fallback, { recursive: true });
+    return fallback;
+  }
+}
+
+/**
+ * Pre-build (cached) @checkstack/ui's Monaco language workers and return the
+ * Vite wiring that redirects its `?worker&url` imports to the pre-built
+ * bundles. See {@link prepareMonacoWorkers}. Returns `undefined` (editor
+ * degrades gracefully) on any failure.
+ */
+async function loadMonacoWorkers({
+  frontendDir,
+  pluginCwd,
+  vscodeDir,
+  buildFn,
+}: {
+  frontendDir: string;
+  pluginCwd: string;
+  vscodeDir: string;
+  buildFn: ViteBuild;
+}): Promise<MonacoWorkerSetup | undefined> {
+  return prepareMonacoWorkers({
+    resolveFrom: monacoResolveFrom({ frontendDir, pluginCwd }),
+    vscodeDir,
+    cacheBaseDir: monacoWorkerCacheDir({ pluginCwd }),
+    buildFn,
+  });
+}
+
 /**
  * Assemble the dev PostCSS plugin chain — the shared `@checkstack/frontend`
  * Tailwind preset (theme + `tailwindcss-animate`) with a `content` glob set

package/src/dev-monaco-workers.test.ts

@@ -0,0 +1,136 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  __test,
+  prepareMonacoWorkers,
+  type ViteBuild,
+} from "./dev-monaco-workers";
+
+// `@codingame/*` worker entries live in `@checkstack/ui`'s deps (two levels up).
+const UI_DIR = path.resolve(import.meta.dir, "../../ui");
+const VSCODE_DIR = "/fake/vscode";
+
+const tmpDirs: string[] = [];
+function makeCacheBase(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ccmw-test-"));
+  tmpDirs.push(dir);
+  return dir;
+}
+afterEach(() => {
+  while (tmpDirs.length) fs.rmSync(tmpDirs.pop()!, { recursive: true, force: true });
+});
+
+/** A build that just writes a dummy bundle where vite would, tracking calls. */
+function fakeBuild(): { fn: ViteBuild; calls: () => number } {
+  let calls = 0;
+  const fn: ViteBuild = (config) => {
+    calls++;
+    const b = config.build;
+    if (!b?.outDir || !b.lib || typeof b.lib === "boolean") {
+      throw new Error("unexpected build config");
+    }
+    const name =
+      typeof b.lib.fileName === "function"
+        ? b.lib.fileName("es", "entry")
+        : String(b.lib.fileName);
+    fs.writeFileSync(path.join(b.outDir, name), "export default {};\n");
+    return Promise.resolve();
+  };
+  return { fn, calls: () => calls };
+}
+
+describe("computeCacheKey", () => {
+  it("is deterministic for the same inputs", () => {
+    const a = __test.computeCacheKey({ vscodeDir: "/x", versions: ["1", "2"] });
+    const b = __test.computeCacheKey({ vscodeDir: "/x", versions: ["1", "2"] });
+    expect(a).toBe(b);
+  });
+
+  it("changes when the vscode dir or a worker version changes", () => {
+    const base = __test.computeCacheKey({ vscodeDir: "/x", versions: ["1"] });
+    expect(__test.computeCacheKey({ vscodeDir: "/y", versions: ["1"] })).not.toBe(base);
+    expect(__test.computeCacheKey({ vscodeDir: "/x", versions: ["2"] })).not.toBe(base);
+  });
+});
+
+describe("buildAliases", () => {
+  it("redirects each `?worker&url` import to its stub", () => {
+    const aliases = __test.buildAliases("/cache");
+    expect(aliases).toHaveLength(__test.WORKERS.length);
+    for (const w of __test.WORKERS) {
+      const a = aliases.find((x) => (x.find as RegExp).test(`${w.spec}?worker&url`));
+      expect(a).toBeDefined();
+      expect(a!.replacement).toBe(__test.stubFile("/cache", w.name));
+      // Must NOT match the bare specifier without the worker query.
+      expect((a!.find as RegExp).test(w.spec)).toBe(false);
+    }
+  });
+});
+
+describe("prepareMonacoWorkers", () => {
+  it("builds once, then reuses the cache on a second call", async () => {
+    const cacheBaseDir = makeCacheBase();
+    const first = fakeBuild();
+    const setupA = await prepareMonacoWorkers({
+      resolveFrom: [UI_DIR],
+      vscodeDir: VSCODE_DIR,
+      cacheBaseDir,
+      buildFn: first.fn,
+    });
+    expect(setupA).toBeDefined();
+    expect(first.calls()).toBe(__test.WORKERS.length); // one build per worker
+    expect(setupA!.aliases).toHaveLength(__test.WORKERS.length);
+
+    // Stubs export the served worker URLs.
+    for (const w of __test.WORKERS) {
+      const stub = setupA!.aliases.find(
+        (a) => a.replacement.endsWith(`${w.name}.stub.js`),
+      )!.replacement;
+      expect(fs.readFileSync(stub, "utf8")).toContain(
+        `${__test.SERVE_PREFIX}${w.name}.worker.js`,
+      );
+    }
+
+    // Second call: same inputs → cache hit, build NOT invoked again.
+    const second = fakeBuild();
+    const setupB = await prepareMonacoWorkers({
+      resolveFrom: [UI_DIR],
+      vscodeDir: VSCODE_DIR,
+      cacheBaseDir,
+      buildFn: second.fn,
+    });
+    expect(setupB).toBeDefined();
+    expect(second.calls()).toBe(0);
+  });
+
+  it("returns undefined and leaves no ready cache when the build fails", async () => {
+    const cacheBaseDir = makeCacheBase();
+    const failing: ViteBuild = () => Promise.reject(new Error("boom"));
+    const setup = await prepareMonacoWorkers({
+      resolveFrom: [UI_DIR],
+      vscodeDir: VSCODE_DIR,
+      cacheBaseDir,
+      buildFn: failing,
+    });
+    expect(setup).toBeUndefined();
+    // No promoted cache dir was left behind (only the base remains).
+    const entries = fs
+      .readdirSync(cacheBaseDir)
+      .filter((e) => __test.isCacheReady(path.join(cacheBaseDir, e)));
+    expect(entries).toHaveLength(0);
+  });
+
+  it("returns undefined when the editor stack can't be resolved", async () => {
+    const cacheBaseDir = makeCacheBase();
+    const { fn } = fakeBuild();
+    const setup = await prepareMonacoWorkers({
+      resolveFrom: [path.join(cacheBaseDir, "does-not-exist")],
+      vscodeDir: VSCODE_DIR,
+      cacheBaseDir,
+      buildFn: fn,
+    });
+    expect(setup).toBeUndefined();
+  });
+});

package/src/dev-monaco-workers.ts

@@ -0,0 +1,300 @@
+/**
+ * Standalone Monaco worker pre-build for the dev server.
+ *
+ * `@checkstack/ui`'s `CodeEditor` imports three Monaco language workers via
+ * `?worker&url`:
+ *
+ * - the generic editor worker (`@codingame/monaco-vscode-editor-api`)
+ * - the TypeScript/JavaScript language worker
+ * - the JSON language worker
+ *
+ * In the monorepo `@checkstack/ui` is a linked workspace *source* package, so
+ * Vite's worker handling processes those imports normally. In a standalone
+ * plugin it is a *pre-bundled npm dependency*, and Vite's worker plugin does
+ * NOT run during dependency pre-bundling - the optimizer then chokes on the
+ * `?worker&url` query and the dev server crashes. Serving `@checkstack/ui` as
+ * source instead breaks the CJS->ESM interop of its other deps (`ajv`,
+ * `cookie`, ...).
+ *
+ * This module breaks that deadlock: it pre-builds each worker into a
+ * self-contained ES-module bundle (a plain `vite build`, NOT the dep
+ * optimizer, so the worker query never reaches it), serves them as static
+ * files, and exposes `resolve.alias` entries that redirect each `?worker&url`
+ * import to a tiny stub returning the served URL. Because `resolve.alias` runs
+ * during pre-bundling, `@checkstack/ui` stays pre-bundled (its CJS deps keep
+ * their interop) while the worker imports resolve to the pre-built bundles.
+ *
+ * The workers are self-contained Monaco language-service code (they do not pull
+ * in `@checkstack/ui`'s app dependencies), so building them in isolation is
+ * clean.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import type { Alias, InlineConfig, Plugin } from "vite";
+
+/**
+ * Bump when the build config or stub/serve contract below changes, so existing
+ * caches from older dev-server versions are invalidated.
+ */
+const CACHE_FORMAT = "1";
+
+/** URL prefix the pre-built workers are served under. */
+const SERVE_PREFIX = "/@checkstack-monaco-worker/";
+
+/**
+ * The three worker entry imports `@checkstack/ui`'s `monacoTsService` pulls in.
+ * `spec` is the bare specifier exactly as written there (sans the `?worker&url`
+ * suffix); `pkg` is the owning package (used to key the cache on its version).
+ */
+const WORKERS = [
+  {
+    name: "editor",
+    pkg: "@codingame/monaco-vscode-editor-api",
+    spec: "@codingame/monaco-vscode-editor-api/esm/vs/editor/editor.worker.js",
+  },
+  {
+    name: "ts",
+    pkg: "@codingame/monaco-vscode-standalone-typescript-language-features",
+    spec: "@codingame/monaco-vscode-standalone-typescript-language-features/worker",
+  },
+  {
+    name: "json",
+    pkg: "@codingame/monaco-vscode-standalone-json-language-features",
+    spec: "@codingame/monaco-vscode-standalone-json-language-features/worker",
+  },
+] as const;
+
+/** Vite's `build` (injected so this module stays decoupled / unit-testable). */
+export type ViteBuild = (config: InlineConfig) => Promise<unknown>;
+
+export interface MonacoWorkerSetup {
+  /** `resolve.alias` entries redirecting each `?worker&url` import to a stub. */
+  aliases: Alias[];
+  /** Vite plugin that serves the pre-built worker bundles as static files. */
+  plugin: Plugin;
+}
+
+const escapeRegExp = (s: string) =>
+  s.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+
+/** `.../foo.worker.js` built bundle path inside a cache dir. */
+const workerFile = (dir: string, name: string) =>
+  path.join(dir, `${name}.worker.js`);
+/** `.../foo.stub.js` redirect stub path inside a cache dir. */
+const stubFile = (dir: string, name: string) => path.join(dir, `${name}.stub.js`);
+const readyMarker = (dir: string) => path.join(dir, ".ready");
+
+/**
+ * Read a package's version via its resolvable `package.json`, or `"?"` when it
+ * can't be resolved (still produces a stable, distinct cache key).
+ */
+function readPkgVersion({
+  pkg,
+  req,
+  paths,
+}: {
+  pkg: string;
+  req: NodeJS.Require;
+  paths: string[];
+}): string {
+  try {
+    const pkgJsonPath = req.resolve(`${pkg}/package.json`, { paths });
+    const parsed: unknown = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      "version" in parsed &&
+      typeof (parsed as { version: unknown }).version === "string"
+    ) {
+      return (parsed as { version: string }).version;
+    }
+  } catch {
+    // fall through
+  }
+  return "?";
+}
+
+/**
+ * Deterministic cache key over everything that affects the built output: the
+ * cache format, the resolved `vscode` alias dir, and each worker package's
+ * version. A dependency bump (or a config change via `CACHE_FORMAT`) yields a
+ * new key, so stale bundles are never reused.
+ */
+function computeCacheKey({
+  vscodeDir,
+  versions,
+}: {
+  vscodeDir: string;
+  versions: string[];
+}): string {
+  return createHash("sha256")
+    .update(JSON.stringify([CACHE_FORMAT, vscodeDir, versions]))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/** A cache dir is usable only if every worker + stub exists AND `.ready` does. */
+function isCacheReady(dir: string): boolean {
+  if (!fs.existsSync(readyMarker(dir))) return false;
+  return WORKERS.every(
+    (w) => fs.existsSync(workerFile(dir, w.name)) && fs.existsSync(stubFile(dir, w.name)),
+  );
+}
+
+function buildAliases(cacheDir: string): Alias[] {
+  return WORKERS.map((w) => ({
+    // Matches the exact `?worker&url` import in monacoTsService, so the worker
+    // resolves to the stub (which exports the served URL) during pre-bundling.
+    find: new RegExp(`^${escapeRegExp(`${w.spec}?worker&url`)}$`),
+    replacement: stubFile(cacheDir, w.name),
+  }));
+}
+
+function buildServePlugin(cacheDir: string): Plugin {
+  return {
+    name: "checkstack-dev-monaco-workers",
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const url = req.url ?? "";
+        if (!url.startsWith(SERVE_PREFIX)) return next();
+        const name = url.slice(SERVE_PREFIX.length).replace(/\?.*$/, "");
+        const match = WORKERS.find((w) => `${w.name}.worker.js` === name);
+        const file = match ? workerFile(cacheDir, match.name) : undefined;
+        if (!file || !fs.existsSync(file)) {
+          res.statusCode = 404;
+          res.end("worker not found");
+          return;
+        }
+        res.setHeader("Content-Type", "text/javascript; charset=utf-8");
+        // Pre-built and content-keyed by the cache dir, so it's immutable.
+        res.setHeader("Cache-Control", "no-cache");
+        fs.createReadStream(file).pipe(res);
+      });
+    },
+  };
+}
+
+/**
+ * Build the three workers into `destDir` and write their redirect stubs. Each
+ * worker is a separate `vite build` in library mode (single ES module, inlined
+ * dynamic imports) with the `vscode` alias applied - identical to how the
+ * production build bundles them, never touching the dep optimizer.
+ */
+async function buildWorkersInto({
+  destDir,
+  entries,
+  vscodeDir,
+  buildFn,
+}: {
+  destDir: string;
+  entries: { name: string; entry: string }[];
+  vscodeDir: string;
+  buildFn: ViteBuild;
+}): Promise<void> {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const { name, entry } of entries) {
+    await buildFn({
+      configFile: false,
+      logLevel: "silent",
+      resolve: { alias: { vscode: vscodeDir } },
+      worker: { format: "es" },
+      build: {
+        outDir: destDir,
+        emptyOutDir: false,
+        target: "esnext",
+        minify: true,
+        lib: { entry, formats: ["es"], fileName: () => `${name}.worker.js` },
+        rollupOptions: { output: { inlineDynamicImports: true } },
+        write: true,
+      },
+    });
+    fs.writeFileSync(
+      stubFile(destDir, name),
+      `export default ${JSON.stringify(`${SERVE_PREFIX}${name}.worker.js`)};\n`,
+    );
+  }
+  fs.writeFileSync(readyMarker(destDir), `${Date.now()}\n`);
+}
+
+/**
+ * Pre-build (or reuse a cached build of) the Monaco workers and return the Vite
+ * wiring (`resolve.alias` redirects + a static-serving plugin).
+ *
+ * Returns `undefined` on any failure (editor stack unresolvable, build error) -
+ * the dev server still starts; the editor just won't get its language workers.
+ *
+ * Caching is content-addressed and concurrency-safe: builds go to a unique
+ * temp dir and are atomically promoted to the keyed cache dir only once
+ * complete, so a crashed or racing build never yields a partial cache, and two
+ * dev servers building the same versions converge on one result.
+ */
+export async function prepareMonacoWorkers({
+  resolveFrom,
+  vscodeDir,
+  cacheBaseDir,
+  buildFn,
+}: {
+  resolveFrom: string[];
+  vscodeDir: string;
+  cacheBaseDir: string;
+  buildFn: ViteBuild;
+}): Promise<MonacoWorkerSetup | undefined> {
+  try {
+    const req = createRequire(path.join(cacheBaseDir, "noop.js"));
+    const entries = WORKERS.map((w) => ({
+      name: w.name,
+      entry: req.resolve(w.spec, { paths: resolveFrom }),
+    }));
+    const versions = WORKERS.map((w) =>
+      readPkgVersion({ pkg: w.pkg, req, paths: resolveFrom }),
+    );
+
+    const key = computeCacheKey({ vscodeDir, versions });
+    const cacheDir = path.join(cacheBaseDir, key);
+
+    if (!isCacheReady(cacheDir)) {
+      const tmpDir = `${cacheDir}.tmp-${process.pid}-${createHash("sha256")
+        .update(`${Date.now()}:${entries.map((e) => e.entry).join(",")}`)
+        .digest("hex")
+        .slice(0, 8)}`;
+      try {
+        await buildWorkersInto({ destDir: tmpDir, entries, vscodeDir, buildFn });
+        // Another dev server may have finished the same build while we were
+        // working: prefer the existing cache and discard our temp.
+        if (isCacheReady(cacheDir)) {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        } else {
+          try {
+            fs.renameSync(tmpDir, cacheDir);
+          } catch {
+            // Lost a promote race (dir now exists) - fine if it's ready.
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+            if (!isCacheReady(cacheDir)) throw new Error("worker cache promote failed");
+          }
+        }
+      } finally {
+        if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+      }
+    }
+
+    if (!isCacheReady(cacheDir)) return undefined;
+    return { aliases: buildAliases(cacheDir), plugin: buildServePlugin(cacheDir) };
+  } catch {
+    return undefined;
+  }
+}
+
+// Exposed for unit tests.
+export const __test = {
+  WORKERS,
+  CACHE_FORMAT,
+  SERVE_PREFIX,
+  computeCacheKey,
+  isCacheReady,
+  buildAliases,
+  workerFile,
+  stubFile,
+  readyMarker,
+};