@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/bundle.ts

@@ -0,0 +1,546 @@
+// Bundles a realm.ts source into a self-contained JS string for QuickJS
+// evaluation. The bundling step is independent of permission shape.
+
+import { dirname, join } from "@std/path";
+import { log } from "@local/logger";
+import { pkgRoot } from "./pkg-root.ts";
+import { RealmCompileError } from "./errors.ts";
+import { sha256Hex } from "./generator/hash.ts";
+import { isPacked } from "./pack.ts";
+import { mergePackedSource } from "./surfaces.ts";
+
+const EVAL_PKG_DIR = pkgRoot(import.meta.url);
+
+// `preact` and `preact/hooks` are allowed because surface render fns import
+// hooks directly from preact, and the static import has to resolve at QuickJS
+// bundle time. The imports never fire inside QuickJS — render fns only run in
+// the iframe — so both specifiers alias to local noop stubs below rather than
+// pulling real preact into the sandbox bundle.
+const ALLOWED_IMPORT_PREFIXES = ["@yourrealm/sdk", "preact"];
+
+function validateImports(source: string): void {
+  const importPattern = /(?:import|export)\s.*?from\s+["']([^"']+)["']|import\s*["']([^"']+)["']/g;
+  let match;
+  while ((match = importPattern.exec(source)) !== null) {
+    const specifier = match[1] ?? match[2]!;
+    if (specifier.startsWith("./") || specifier.startsWith("../") || specifier.startsWith("/")) {
+      throw new RealmCompileError({
+        kind: "validation",
+        path: ["imports"],
+        message: `blocked specifier: ${specifier}`,
+      });
+    }
+    if (!ALLOWED_IMPORT_PREFIXES.some((p) => specifier === p || specifier.startsWith(p + "/"))) {
+      throw new RealmCompileError({
+        kind: "validation",
+        path: ["imports"],
+        message: `blocked specifier: ${specifier}`,
+      });
+    }
+  }
+}
+
+function findNodeModules(startDir: string): string | null {
+  // Walk up looking for a node_modules that exposes `@yourrealm/sdk`. The first
+  // match isn't always right: when this file lives inside the SDK itself,
+  // `packages/sdk/node_modules/` exists but can't contain `@yourrealm/sdk` (a
+  // package can't depend on itself). The caller's node_modules (Home, an app
+  // dir, the workspace root) is the one esbuild resolves realm.ts's imports in.
+  let dir = startDir;
+  while (true) {
+    const candidate = join(dir, "node_modules");
+    try {
+      Deno.statSync(candidate);
+      try {
+        Deno.statSync(join(candidate, "@yourrealm", "sdk"));
+        return candidate;
+      } catch {
+        // node_modules exists but doesn't expose @yourrealm/sdk - keep walking
+      }
+    } catch {
+      // no node_modules at this level
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// The esbuild binary usually sits in the same node_modules bundle() already
+// resolved (`<nodeModules>/.bin/esbuild`). Spawn that path instead of a bare
+// `esbuild`, which only resolves when the *invoking* package depends on esbuild
+// (Home's runtime ENV, the SDK's own tests) — not when `realm-sdk build` runs
+// from an app dir that doesn't.
+//
+// The second candidate is what pnpm's isolated layout requires: only a
+// package's *direct* dependencies' binaries land in its `.bin`, so an app dir
+// gets `.bin/realm-sdk` and nothing else while esbuild (the SDK's dependency,
+// not the app's) stays in `packages/sdk/node_modules/.bin`. A bare `esbuild` is
+// the last resort, and only resolves when something put it on PATH.
+export function esbuildBinIn(nodeModules: string | null): string {
+  const candidates = [
+    nodeModules === null ? null : join(nodeModules, ".bin", "esbuild"),
+    EVAL_PKG_DIR === null ? null : join(EVAL_PKG_DIR, "node_modules", ".bin", "esbuild"),
+  ];
+  for (const candidate of candidates) {
+    if (candidate === null) continue;
+    try {
+      Deno.statSync(candidate);
+      return candidate;
+    } catch {
+      // not here - try the next candidate
+    }
+  }
+  return "esbuild";
+}
+
+// A process-stable dir per resolved node_modules, holding a single
+// `node_modules` symlink. Each bundle runs in a temp *subdir* of it and lets
+// esbuild walk up to resolve `@yourrealm/sdk`, so the symlink is created once
+// rather than per call: per-call create/remove churn races under concurrent
+// bundling (`deno test --parallel`), where esbuild fails EINVAL/ENOENT on the
+// just-created symlink. Roots leak for the process lifetime (one tiny symlink
+// dir each) - the OS reclaims /tmp.
+const bundleRoots = new Map<string, string>();
+function bundleRootFor(nodeModules: string): string {
+  const cached = bundleRoots.get(nodeModules);
+  if (cached) return cached;
+  const root = Deno.makeTempDirSync({ prefix: "realm-bundle-root-" });
+  Deno.symlinkSync(nodeModules, join(root, "node_modules"));
+  bundleRoots.set(nodeModules, root);
+  return root;
+}
+
+// ---- on-disk bundle cache ---------------------------------------------------
+//
+// Memoize successful bundles. Recompute re-evals every app on every trigger
+// (webhook, boot, deploy) and each eval re-bundles, so without this an unchanged
+// app re-spawns esbuild on every reconcile.
+//
+// The cache lives on disk rather than in the heap because of what it holds: a
+// bundle is ~610KB, ~110ms of esbuild to produce, ~0.4ms to read back. An in-RAM
+// map is ~610MB at 1000 apps, and capping it evicts every entry before reuse,
+// because a recompute touches every installed app. Disk has neither problem.
+//
+// Content-addressed like `ui-bundle-storage.ts`: `<key>.js`, written
+// tmp-then-rename so a partial file is never visible at the real path. Nothing
+// here is durable - the whole directory can be deleted at any moment, at a cost
+// of one rebuild per app.
+
+const HASH_RE = /^[0-9a-f]{64}$/;
+
+let cacheDirOverride: string | null = null;
+let cacheDirResolved: string | null | undefined;
+let buildId: string | null = null;
+
+/**
+ * Point the bundle cache at a persistent directory. Home calls this at boot with
+ * a path under `HOME_DATA_DIR` so the cache survives a restart. Everything else
+ * (the CLI, app tests, `realm-sdk dev`) leaves it unset and shares one directory
+ * under the temp dir, which a container start wipes and the OS reclaims.
+ *
+ * `buildId` identifies the shipped build of the SDK, and a persistent directory
+ * needs one whenever the SDK isn't on disk as source - see `sdkFingerprint`.
+ * Without it the persistent directory is refused and the ephemeral one used
+ * instead: slower, never stale.
+ */
+export function setBundleCacheDir(dir: string, opts?: { buildId?: string }): void {
+  cacheDirOverride = dir;
+  buildId = opts?.buildId ?? null;
+  cacheDirResolved = undefined;
+  fingerprint = null;
+}
+
+/** Shared by every process that didn't ask for a directory. */
+function ephemeralCacheDir(): string | null {
+  const base = Deno.env.get("TMPDIR") ?? "/tmp";
+  // One shared directory, not one per process: a per-process temp dir is never
+  // reclaimed until the OS gets to it, and `pnpm test` alone spawns dozens.
+  // Sharing is safe because entries are content-addressed.
+  for (const dir of [join(base, "realm-bundle-cache"), null]) {
+    try {
+      if (dir === null) return Deno.makeTempDirSync({ prefix: "realm-bundle-cache-" });
+      Deno.mkdirSync(dir, { recursive: true });
+      return dir;
+    } catch {
+      // Try the next candidate; a null return disables caching entirely.
+    }
+  }
+  return null;
+}
+
+/** Where bundles land, or `null` when nothing is usable and we bundle uncached. */
+function bundleCacheDir(): string | null {
+  if (cacheDirResolved !== undefined) return cacheDirResolved;
+  if (cacheDirOverride !== null) {
+    try {
+      Deno.mkdirSync(cacheDirOverride, { recursive: true });
+      cacheDirResolved = cacheDirOverride;
+      return cacheDirResolved;
+    } catch (err) {
+      // A read-only or full data dir costs speed, not correctness. Falling back
+      // rather than throwing keeps an unwritable dir from failing every compile,
+      // which would turn Home's default-app seeding into a crashloop.
+      log.warn(`bundle cache: ${cacheDirOverride} unusable, falling back: ${String(err)}`);
+    }
+  }
+  cacheDirResolved = ephemeralCacheDir();
+  return cacheDirResolved;
+}
+
+// The key has to cover the SDK build as well as the app source: esbuild inlines
+// `@yourrealm/sdk` into every bundle, so one realm.ts compiles to different
+// output after an SDK change, and a cache on disk outlives the process and, in
+// production, the *image* (HOME_DATA_DIR survives an upgrade).
+//
+// Only one of the two layouts can be fingerprinted from disk:
+//
+//   dev checkout - `@yourrealm/sdk` resolves to `packages/sdk`, so `src/` holds
+//     every input, including this file (the esbuild argv and the preact/jsx stub
+//     text inlined into every bundle) and `surfaces.ts` (which rewrites a packed
+//     app's source before esbuild sees it). Hashing `src/` is sound.
+//
+//   Home image - only the pre-bundled `dist/` is staged, built from the barrel
+//     entries alone. This file, `surfaces.ts`, `pack.ts`, `compile.ts` and
+//     `sandbox.ts` are NOT in it - they can't be, they touch `Deno` at module
+//     scope - so the files that decide bundle output are exactly the ones a
+//     `dist/` hash misses.
+//
+// A dist-only layout therefore needs `buildId` from the caller (Home passes the
+// image's GIT_HASH). Without one the persistent directory is refused outright,
+// because a cache that cannot be invalidated is worse than no cache.
+let fingerprint: Promise<string> | null = null;
+
+function sdkFingerprint(): Promise<string> {
+  if (fingerprint === null) {
+    const pending = computeSdkFingerprint();
+    // Don't pin a rejection: this tree is known to throw transiently (see the
+    // esbuild retry note below), and a memoized failure would fail every
+    // compile for the life of the process.
+    pending.catch(() => {
+      if (fingerprint === pending) fingerprint = null;
+    });
+    fingerprint = pending;
+  }
+  return fingerprint;
+}
+
+async function collectSdkFiles(root: string, dir: string, out: string[]): Promise<void> {
+  const entries = [];
+  for await (const entry of Deno.readDir(dir)) entries.push(entry);
+  // readDir order isn't stable across filesystems and the hash is order-
+  // sensitive: two boxes must agree on the key to reuse a restored cache.
+  entries.sort((a, b) => (a.name < b.name ? -1 : 1));
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory) {
+      if (entry.name === "node_modules") continue; // a dev checkout has one; esbuild reaches it by resolution, not by path
+      await collectSdkFiles(root, path, out);
+    } else if (/\.(ts|tsx|js|mjs|json)$/.test(entry.name)) {
+      // Relative to the SDK root, so where the checkout happens to live doesn't
+      // change the key - a restored HOME_DATA_DIR keeps working.
+      out.push(path.slice(root.length), await Deno.readTextFile(path));
+    }
+  }
+}
+
+async function computeSdkFingerprint(): Promise<string> {
+  const nodeModules = findNodeModules(
+    Deno.env.get("ESBUILD_RESOLVE_DIR") ?? EVAL_PKG_DIR ?? Deno.cwd(),
+  );
+  const sdkDir = nodeModules === null ? EVAL_PKG_DIR : join(nodeModules, "@yourrealm", "sdk");
+  if (sdkDir === null) {
+    throw new Error(
+      "bundle cache: no node_modules exposes @yourrealm/sdk and the SDK package is not on disk",
+    );
+  }
+  const parts: string[] = [];
+  let hashedSource = false;
+  for (const sub of ["src", "dist"]) {
+    // Probe the subdir, then walk it unguarded: guarding the whole walk would
+    // swallow a NotFound raised *inside* it - a file vanishing mid-walk - and
+    // memoize the truncated prefix as if it were the whole tree, exactly the
+    // staleness this fingerprint exists to prevent.
+    try {
+      if (!(await Deno.stat(join(sdkDir, sub))).isDirectory) continue;
+    } catch (e) {
+      if (e instanceof Deno.errors.NotFound) continue;
+      throw e;
+    }
+    await collectSdkFiles(sdkDir, join(sdkDir, sub), parts);
+    if (sub === "src") hashedSource = true;
+  }
+  if (parts.length === 0) {
+    throw new Error(
+      `bundle cache: no SDK sources under ${sdkDir}/{src,dist} to fingerprint - ` +
+        `a cached bundle could not be invalidated when the SDK changes`,
+    );
+  }
+  // `dist/` alone cannot identify the bundler (see the note above), so a caller
+  // that wants a persistent directory has to name its build. Refuse the
+  // directory rather than hand back a key that can't invalidate.
+  if (buildId !== null) parts.push(`buildId:${buildId}`);
+  if (!hashedSource && buildId === null && cacheDirOverride !== null) {
+    log.warn(
+      `bundle cache: ${sdkDir} ships no src/ and no buildId was given, ` +
+        `so ${cacheDirOverride} can't be invalidated - using an ephemeral cache`,
+    );
+    cacheDirOverride = null;
+    cacheDirResolved = undefined;
+  }
+  // package.json too, for its dependency ranges and `exports` map. It is the one
+  // input not covered exactly: a `pnpm update` inside an unchanged range swaps
+  // an inlined dependency without moving anything hashed here. The image path
+  // has no such gap (dist/ is pre-bundled, so a dependency bump rewrites it),
+  // and a dev checkout clears the cache with the rest of dev state.
+  try {
+    parts.push("package.json", await Deno.readTextFile(join(sdkDir, "package.json")));
+  } catch (e) {
+    if (!(e instanceof Deno.errors.NotFound)) throw e;
+  }
+  // The esbuild binary is the other input to the output. Stat rather than
+  // `--version`: a spawn costs more than the whole tree read above, and a
+  // swapped binary moves size and mtime together.
+  try {
+    const stat = Deno.statSync(esbuildBinIn(nodeModules));
+    parts.push(`esbuild:${stat.size}:${stat.mtime?.getTime() ?? 0}`);
+  } catch {
+    // Not resolvable here - bundling itself will fail next, with a better message.
+  }
+  return await sha256Hex(parts.join("\0"));
+}
+
+// Collapses concurrent callers asking for the same source onto one esbuild run
+// (multi-worker recompute, `deno test --parallel`). Entries are deleted the
+// moment they settle, so nothing is retained here - that is the disk's job - and
+// a transient esbuild flake (see the retry note below) isn't pinned.
+const inFlight = new Map<string, Promise<string>>();
+
+/**
+ * Bundle realm.ts source into a self-contained JS string.
+ * Inlines @yourrealm/sdk and all dependencies (zod, dayjs).
+ * Output is an IIFE that assigns the module exports to `__realm_module__`.
+ *
+ * Uses esbuild CLI binary (not the JS API) so it works when Home
+ * is bundled into a single file by Deno.bundle(). Memoized on disk.
+ */
+export async function bundle(source: string): Promise<string> {
+  const key = await sha256Hex(`${await sdkFingerprint()}\0${source}`);
+  const existing = inFlight.get(key);
+  if (existing) return await existing;
+  // No await between the call and the set, so two callers can't both miss.
+  const pending = bundleThroughDisk(key, source);
+  inFlight.set(key, pending);
+  try {
+    return await pending;
+  } finally {
+    inFlight.delete(key);
+  }
+}
+
+async function bundleThroughDisk(key: string, source: string): Promise<string> {
+  const dir = bundleCacheDir();
+  if (dir === null) return await bundleUncached(source);
+  const path = join(dir, `${key}.js`);
+  try {
+    const hit = await Deno.readTextFile(path);
+    // A hit has to look like esbuild's output before it is trusted. `rename`
+    // isn't preceded by an fsync, so a crash in that window can leave a torn or
+    // empty file at the real path - and since every read below refreshes the
+    // mtime, the age sweep would never reap it. Falling through rebuilds and
+    // overwrites it instead.
+    if (!hit.includes("__realm_module__")) throw new Deno.errors.NotFound(path);
+    // Keep entries in use young, so the sweep reaps only what stopped being read
+    // (an app's previous source, a discarded install preview) and never an
+    // installed app. Awaited rather than floated: an op still in flight when a
+    // test ends is what `deno test`'s sanitizer reports as a leak, and one
+    // stat-sized write against a ~110ms miss isn't worth that class of flake.
+    try {
+      const now = new Date();
+      await Deno.utime(path, now, now);
+    } catch {
+      // A read-only cache dir still serves reads; it just can't age entries.
+    }
+    return hit;
+  } catch (e) {
+    if (!(e instanceof Deno.errors.NotFound)) throw e;
+  }
+
+  const code = await bundleUncached(source);
+  try {
+    const tmp = `${path}.tmp-${crypto.randomUUID()}`;
+    await Deno.writeTextFile(tmp, code);
+    await Deno.rename(tmp, path);
+  } catch {
+    // A full or read-only cache dir costs speed, not correctness - the bundle in
+    // hand is already good. Swallow so a deploy never fails on a cache write.
+  }
+  return code;
+}
+
+/**
+ * Delete cached bundles that nothing has read for `maxAgeMs`, plus any
+ * `.tmp-*` file a crash left mid-write. Returns the number of files removed.
+ *
+ * Age, not liveness: the key is a hash of (SDK build + source), so there is no
+ * app id to match rows against, and an app that changes its source orphans its
+ * old entry with no event to hang a sweep off. Reads keep live entries young,
+ * so an installed app is never reaped no matter how long it sits unchanged.
+ *
+ * Per-file errors are swallowed so one bad file doesn't stop the sweep.
+ */
+export async function sweepBundleCache(maxAgeMs: number): Promise<number> {
+  const dir = bundleCacheDir();
+  if (dir === null) return 0;
+  const cutoff = Date.now() - maxAgeMs;
+  let removed = 0;
+  try {
+    // Deno.readDir is lazy - a missing dir surfaces on first iteration.
+    for await (const entry of Deno.readDir(dir)) {
+      if (!entry.isFile) continue;
+      const stale = /\.tmp-[0-9a-f-]+$/.test(entry.name);
+      if (!stale && !(entry.name.endsWith(".js") && HASH_RE.test(entry.name.slice(0, -3))))
+        continue;
+      const path = join(dir, entry.name);
+      try {
+        const stat = await Deno.stat(path);
+        if ((stat.mtime?.getTime() ?? 0) > cutoff) continue;
+        await Deno.remove(path);
+        removed++;
+      } catch {
+        // Best effort - the next sweep picks up survivors.
+      }
+    }
+  } catch (e) {
+    if (e instanceof Deno.errors.NotFound) return 0;
+    throw e;
+  }
+  return removed;
+}
+
+async function bundleUncached(source: string): Promise<string> {
+  const resolveDir = Deno.env.get("ESBUILD_RESOLVE_DIR") ?? EVAL_PKG_DIR ?? Deno.cwd();
+
+  // A packed artifact is unpacked and its file-based surfaces merged in here, at
+  // install — with esbuild alone, no TypeScript compiler, so it is safe in Home.
+  // A plain (unmarked) source passes straight through, and the merge inlines
+  // relatives so validateImports below still only sees the package allowlist.
+  if (isPacked(source)) source = await mergePackedSource(source);
+
+  validateImports(source);
+
+  // Run inside a subdir of the shared root (which holds the one node_modules
+  // symlink) so esbuild resolves @yourrealm/sdk by walking up - no per-call
+  // symlink. With no node_modules found it falls back to a bare /tmp dir, where
+  // esbuild cannot resolve the SDK.
+  const nodeModules = findNodeModules(resolveDir);
+  const root = nodeModules ? bundleRootFor(nodeModules) : undefined;
+  const tmpDir = await Deno.makeTempDir(
+    root ? { dir: root, prefix: "b-" } : { prefix: "realm-bundle-" },
+  );
+  // Always .tsx so esbuild's tsx loader handles both plain TS and JSX. The
+  // render fns inside `ui:` surfaces never run inside QuickJS (only their
+  // existence is checked), so the JSX compiles to captured `h(...)` calls that
+  // fire only when the iframe runtime mounts.
+  const tmpFile = join(tmpDir, "realm-eval.tsx");
+  // esbuild's automatic JSX transform emits `import { jsx } from
+  // "@yourrealm/sdk/jsx-runtime"` for every JSX element, and the SDK's
+  // jsx-runtime entry re-exports preact/jsx-runtime — which Home's runtime image
+  // does not stage. The QuickJS bundle never invokes render, so these stubs in
+  // the same tmpdir let esbuild short-circuit the chain locally.
+  const jsxStubPath = join(tmpDir, "jsx-runtime-stub.js");
+  const preactStubPath = join(tmpDir, "preact-stub.js");
+  const preactHooksStubPath = join(tmpDir, "preact-hooks-stub.js");
+
+  try {
+    await Deno.writeTextFile(tmpFile, source);
+    await Deno.writeTextFile(
+      jsxStubPath,
+      // Identity / noop exports. Render fns capture these in their
+      // closure but never invoke them inside QuickJS.
+      "const noop = () => null;\n" +
+        "export const jsx = noop;\n" +
+        "export const jsxs = noop;\n" +
+        "export const jsxDEV = noop;\n" +
+        "export const Fragment = noop;\n",
+    );
+    await Deno.writeTextFile(
+      preactStubPath,
+      "const noop = () => null;\n" +
+        "export const h = noop;\n" +
+        "export const Fragment = noop;\n" +
+        "export const render = noop;\n",
+    );
+    await Deno.writeTextFile(
+      preactHooksStubPath,
+      // Same shape as preact/hooks at the type level — the render fn captures
+      // these names but never calls them inside QuickJS. The iframe runtime
+      // supplies the real implementations.
+      "const noop = () => {};\n" +
+        "export const useState = (init) => [init, noop];\n" +
+        "export const useEffect = noop;\n" +
+        "export const useMemo = (fn) => fn();\n" +
+        "export const useCallback = (fn) => fn;\n" +
+        "export const useReducer = (_, init) => [init, noop];\n" +
+        "export const useRef = (init) => ({ current: init });\n",
+    );
+
+    const esbuildArgs = [
+      tmpFile,
+      "--bundle",
+      "--format=iife",
+      "--global-name=__realm_module__",
+      "--platform=neutral",
+      "--main-fields=module,main",
+      "--target=es2020",
+      "--jsx=automatic",
+      "--jsx-import-source=@yourrealm/sdk",
+      // Short-circuits the jsx-runtime chain to the local stubs above, so
+      // preact need not be resolvable inside Home's eval image.
+      `--alias:preact/jsx-runtime=${jsxStubPath}`,
+      `--alias:preact/hooks=${preactHooksStubPath}`,
+      `--alias:preact=${preactStubPath}`,
+    ];
+
+    // Retry transient resolution/FS hiccups. Running ~16 esbuild subprocesses at
+    // once (`deno test --parallel`) occasionally trips macOS resolving the SDK
+    // through pnpm's symlinked node_modules — a spurious "Could not resolve",
+    // EINVAL, or ENOENT that clears on a retry. A syntax error doesn't match and
+    // fails on the first attempt; a genuinely unresolvable (but allowlisted) SDK
+    // subpath is textually identical to the transient case, so it pays the
+    // retries and then fails with the same esbuild message.
+    const TRANSIENT =
+      /Could not resolve|Cannot read file|invalid argument|no such file or directory|operation not permitted/;
+    for (let attempt = 0; ; attempt++) {
+      // Re-resolve the binary on each attempt. Under `nodeModulesDir: "auto"`
+      // Deno rebuilds the workspace-member link (node_modules/@yourrealm/sdk) on
+      // every invocation as a remove-then-symlink, leaving a window where the
+      // link is gone; a bundle landing in another process's window resolves no
+      // node_modules, falls back to a bare "esbuild" that isn't on PATH, and
+      // dies. Re-resolving makes that window cost a retry, not the whole eval.
+      let output;
+      try {
+        output = await new Deno.Command(esbuildBinIn(findNodeModules(resolveDir)), {
+          args: esbuildArgs,
+          stdout: "piped",
+          stderr: "piped",
+        }).output();
+      } catch (e) {
+        // A spawn failure throws rather than returning a code, so it would
+        // otherwise skip the retry below entirely.
+        if (attempt >= 2) throw e;
+        await new Promise((r) => setTimeout(r, 20 * (attempt + 1)));
+        continue;
+      }
+      const { code, stdout, stderr } = output;
+      if (code === 0) return new TextDecoder().decode(stdout);
+      const err = new TextDecoder().decode(stderr);
+      if (attempt >= 2 || !TRANSIENT.test(err)) {
+        throw new RealmCompileError({ kind: "eval", message: err });
+      }
+      await new Promise((r) => setTimeout(r, 20 * (attempt + 1)));
+    }
+  } finally {
+    await Deno.remove(tmpDir, { recursive: true }).catch(() => {});
+  }
+}

package/src/cli/build-dev-landing.ts

@@ -0,0 +1,84 @@
+// `realm-sdk build-dev-landing --out <dir>` — esbuild the dev-landing preact
+// entry into `dev-landing.js`, next to `runtime.js`. CSS is shared: runtime.css's
+// Tailwind scan already covers `packages/sdk/src/ui-runtime/dev-landing-entry.tsx`.
+// `realm-sdk dev` builds it alongside runtime.js + install-panel.js on first boot
+// and serves it at `/dev-landing.js`, mounted by a thin HTML shell.
+
+import { resolve } from "@std/path";
+import { sdkDir } from "../pkg-root.ts";
+
+const ENTRY = resolve(sdkDir(import.meta.url), "src/ui-runtime/dev-landing-entry.tsx");
+
+interface BuildOpts {
+  outDir: string;
+}
+
+async function buildJs(outDir: string): Promise<void> {
+  const cmd = new Deno.Command("esbuild", {
+    args: [
+      ENTRY,
+      "--bundle",
+      `--outfile=${outDir}/dev-landing.js`,
+      "--format=esm",
+      "--platform=browser",
+      "--target=es2020",
+      "--main-fields=module,main",
+      "--jsx=automatic",
+      "--jsx-import-source=preact",
+      "--alias:react=preact/compat",
+      "--alias:react-dom=preact/compat",
+      "--alias:react/jsx-runtime=preact/jsx-runtime",
+      '--define:process.env.NODE_ENV="production"',
+      "--minify",
+    ],
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const { code, stderr } = await cmd.output();
+  if (code !== 0) {
+    const err = new TextDecoder().decode(stderr);
+    throw new Error(`esbuild dev-landing failed:\n${err}`);
+  }
+}
+
+async function buildDevLanding(opts: BuildOpts): Promise<void> {
+  const outDir = resolve(Deno.cwd(), opts.outDir);
+  await Deno.mkdir(outDir, { recursive: true });
+  await buildJs(outDir);
+  const jsStat = await Deno.stat(`${outDir}/dev-landing.js`);
+  console.log(`dev-landing → ${outDir}: dev-landing.js (${(jsStat.size / 1024).toFixed(1)} KB)`);
+}
+
+export async function runBuildDevLanding(args: string[]): Promise<number> {
+  let outDir = "./ui-runtime";
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--out" || a === "-o") {
+      const next = args[i + 1];
+      if (!next) {
+        console.error("--out requires a directory argument");
+        return 2;
+      }
+      outDir = next;
+      i++;
+      continue;
+    }
+    if (a === "--help" || a === "-h") {
+      console.log(`Usage: realm-sdk build-dev-landing [--out DIR]
+
+Builds the dev landing entry (dev-landing.js) into DIR.
+DIR defaults to ./ui-runtime (relative to the current directory).
+`);
+      return 0;
+    }
+    console.error(`Unknown flag: ${a}`);
+    return 2;
+  }
+  try {
+    await buildDevLanding({ outDir });
+    return 0;
+  } catch (err) {
+    console.error((err as Error).message);
+    return 1;
+  }
+}