@frockbot/applet-sdk 0.7.179 → 0.7.180

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.179",
+  "version": "0.7.180",
   "private": false,
   "type": "module",
   "description": "Authoring SDK for FrockBot Applets: schema-first Durable Object server, TanStack DB client, component kit, linter, and the build pipeline.",

package/src/build/plugin.ts

@@ -28,11 +28,42 @@ import { convertV4MiniflareOptions, Miniflare } from "miniflare";
 import ts from "typescript";
 
 import type { AppletDiagnostic } from "../lint/index.js";
-import { bootedWithin, withOneMoreBoot } from "./boot.js";
 import { stableModulePaths } from "./module-paths.js";
-import { APPLET_COMPATIBILITY_DATE } from "./runtime.js";
 import { SDK_PLUGIN_TYPES } from "./paths.js";
 
+/** Pinned with the SDK: the runtime a Plugin build is checked against. */
+const PLUGIN_COMPATIBILITY_DATE = "2026-08-27";
+
+/**
+ * A workerd boot takes well under a second; this is room for a loaded
+ * machine. Without it a runtime that never reported ready would hang the
+ * build container's request rather than answer.
+ */
+const BOOT_DEADLINE_MS = 30_000;
+
+/**
+ * Tearing a runtime down takes milliseconds, but Miniflare's dispose first
+ * waits out the startup, which can be the very thing that hung.
+ */
+const DISPOSE_DEADLINE_MS = 10_000;
+
+/** `work`, or an error naming what did not happen in time. */
+async function within<T>(
+  work: Promise<T>,
+  ms: number,
+  what: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${what} within ${ms}ms`)), ms);
+  });
+  try {
+    return await Promise.race([work, deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 export type PluginBuildStage =
   "descriptor" | "typecheck" | "bundle" | "describe";
 
@@ -347,17 +378,11 @@ export default {
 `;
 
 /**
- * Ask the built module what it exports, by running it. The boot is bounded
- * and tried once more (`boot.ts`), so a build answers rather than hanging on
- * a runtime that never came up.
+ * Ask the built module what it exports, by running it. Both the boot and the
+ * teardown are bounded, so a build answers rather than hanging on a runtime
+ * that never came up.
  */
-export function describePlugin(
-  moduleCode: string,
-): Promise<PluginDescriptionV1> {
-  return withOneMoreBoot(() => describeInWorkerd(moduleCode));
-}
-
-async function describeInWorkerd(
+export async function describePlugin(
   moduleCode: string,
 ): Promise<PluginDescriptionV1> {
   const miniflare = new Miniflare(
@@ -367,7 +392,7 @@ async function describeInWorkerd(
         { type: "ESModule", path: "/plugin.js", contents: moduleCode },
       ],
       modulesRoot: "/",
-      compatibilityDate: APPLET_COMPATIBILITY_DATE,
+      compatibilityDate: PLUGIN_COMPATIBILITY_DATE,
       // Import-time code runs with no way out: every fetch is answered here.
       outboundService: async () =>
         new Response("the build describes a Plugin without a network", {
@@ -377,10 +402,12 @@ async function describeInWorkerd(
       port: 0,
     }),
   );
-  let started = false;
   try {
-    const url = await bootedWithin(miniflare.ready);
-    started = true;
+    const url = await within(
+      miniflare.ready,
+      BOOT_DEADLINE_MS,
+      "The Workers runtime did not start",
+    );
     const response = (await miniflare.dispatchFetch(
       new URL(`/describe?${randomUUID()}`, url).toString(),
     )) as unknown as Response;
@@ -392,9 +419,15 @@ async function describeInWorkerd(
     }
     return validateDescription(body.description);
   } finally {
-    // A runtime that never started is let go of rather than waited on.
-    if (started) await miniflare.dispose();
-    else void miniflare.dispose().catch(() => {});
+    // Awaited on every path, a boot that missed its deadline included: this
+    // is what kills workerd. Miniflare's fallback is a process exit hook,
+    // `bun test` runs none, and a dispose still pending when the host exits
+    // leaves workerd running.
+    await within(
+      miniflare.dispose(),
+      DISPOSE_DEADLINE_MS,
+      "The Workers runtime did not stop",
+    );
   }
 }
 

package/src/build/boot.ts

@@ -1,75 +0,0 @@
-// A workerd boot, bounded.
-//
-// Each build spawns its own workerd through Miniflare, and a spawn
-// occasionally never comes up (a bun+workerd spawn race, roughly one boot in
-// fifty): it either never reports ready, or it fails outright and leaves the
-// runtime's stdio socket with nothing to connect to. A build that awaited
-// `ready` unbounded would hang to the test's timeout, or hang the build
-// container's request. So a boot is given a deadline, a boot that misses it
-// is let go of rather than waited on, both shapes are named
-// `RuntimeDidNotStart`, and the caller tries once more before answering with
-// that as its diagnostic.
-
-/** How long a workerd boot is given before the build gives up on it. */
-export const BOOT_DEADLINE_MS = 30_000;
-
-/** A workerd that never came up; the boot, not the code, failed. */
-export class RuntimeDidNotStart extends Error {}
-
-/**
- * The same race seen from the other side: the spawn fails outright rather
- * than hanging, and the runtime's stdio socket is never there to connect to.
- * That is a boot that did not happen, not a fault in the code being built.
- */
-function spawnFailed(error: unknown): boolean {
-  const { code, syscall } = (error ?? {}) as {
-    code?: unknown;
-    syscall?: unknown;
-  };
-  return (
-    (syscall === "connect" || syscall === "spawn") &&
-    (code === "ENOENT" || code === "ECONNREFUSED" || code === "EAGAIN")
-  );
-}
-
-/**
- * `ready`, or a `RuntimeDidNotStart` when the runtime never came up — either
- * because `ready` did not settle in time or because the spawn failed.
- */
-export async function bootedWithin<T>(ready: Promise<T>): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const deadline = new Promise<never>((_, reject) => {
-    timer = setTimeout(
-      () =>
-        reject(
-          new RuntimeDidNotStart(
-            `The Workers runtime did not start within ${BOOT_DEADLINE_MS}ms`,
-          ),
-        ),
-      BOOT_DEADLINE_MS,
-    );
-  });
-  try {
-    return await Promise.race([ready, deadline]);
-  } catch (error) {
-    if (!spawnFailed(error)) throw error;
-    throw new RuntimeDidNotStart(
-      `The Workers runtime could not be spawned: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-      { cause: error },
-    );
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/** Runs `boot` again, once, when the runtime never came up the first time. */
-export async function withOneMoreBoot<T>(boot: () => Promise<T>): Promise<T> {
-  try {
-    return await boot();
-  } catch (error) {
-    if (!(error instanceof RuntimeDidNotStart)) throw error;
-    return await boot();
-  }
-}

package/src/build/runtime.ts

@@ -1,132 +0,0 @@
-/**
- * The built Applet, running for real, in a Node process.
- *
- * Miniflare gives the built `dist/server.js` the one thing no fake can: a
- * SQLite-backed Durable Object with hibernating WebSockets, which is exactly
- * what the loader gives it in production. The build uses it to ask the
- * mounted class what
- * tools it declares rather than guessing from the source.
- */
-
-import { convertV4MiniflareOptions, Miniflare } from "miniflare";
-
-import { bootedWithin } from "./boot.js";
-
-/** Pinned with the SDK: the runtime a Plugin build is checked against. */
-export const APPLET_COMPATIBILITY_DATE = "2026-08-27";
-
-/**
- * The dev worker. It exists only to route: the DO class is the Applet's own,
- * and everything else here is the two seams the kernel provides in production
- * — a viewer token on the socket, and a `CAPABILITIES` binding.
- */
-const DEV_WORKER = `
-export { Applet } from "./server.js";
-
-export default {
-  async fetch(request, env) {
-    const url = new URL(request.url);
-    const stub = env.APPLET.get(env.APPLET.idFromName(env.APPLET_ID));
-
-    if (url.pathname === "/socket") {
-      if (url.searchParams.get("token") !== env.APPLET_TOKEN) {
-        return new Response("Forbidden", { status: 403 });
-      }
-      url.searchParams.set("viewer", url.searchParams.get("viewer") ?? "dev-viewer");
-      return stub.fetch(new Request(url, request));
-    }
-
-    if (url.pathname === "/health") {
-      return Response.json(await stub.health());
-    }
-
-    if (url.pathname === "/describe") {
-      return Response.json(await stub.describe());
-    }
-
-    if (url.pathname === "/tool" && request.method === "POST") {
-      const body = await request.json();
-      try {
-        return Response.json({ ok: true, result: await stub.invokeTool(body.name, body.input) });
-      } catch (error) {
-        return Response.json({ ok: false, error: String(error && error.message || error) });
-      }
-    }
-
-    if (url.pathname === "/" || url.pathname === "/index.html") {
-      return new Response(env.APPLET_UI, {
-        headers: { "content-type": "text/html; charset=utf-8" },
-      });
-    }
-    return new Response("Not found", { status: 404 });
-  },
-};
-`;
-
-export interface AppletRuntimeOptions {
-  /** Contents of `dist/server.js`: one ESM file importing only cloudflare:workers. */
-  serverCode: string;
-  /** Contents of `dist/ui.html`; omitted when only `health()` is wanted. */
-  html?: string;
-  appletId: string;
-  /** The dev viewer token the socket demands. */
-  token: string;
-  /** 0 picks a free port. */
-  port?: number;
-}
-
-export interface AppletRuntime {
-  url: URL;
-  fetch(path: string, init?: RequestInit): Promise<Response>;
-  dispose(): Promise<void>;
-}
-
-export async function startAppletRuntime(
-  options: AppletRuntimeOptions,
-): Promise<AppletRuntime> {
-  // Miniflare 5's own option shape is the wrangler config (`workers[].config`).
-  // `convertV4MiniflareOptions` is the supported way to keep the flat v4 shape,
-  // which is the one the Workers docs and the rest of this repo speak.
-  const miniflare = new Miniflare(
-    convertV4MiniflareOptions({
-      modules: [
-        { type: "ESModule", path: "/index.mjs", contents: DEV_WORKER },
-        { type: "ESModule", path: "/server.js", contents: options.serverCode },
-      ],
-      modulesRoot: "/",
-      compatibilityDate: APPLET_COMPATIBILITY_DATE,
-      compatibilityFlags: ["nodejs_compat"],
-      durableObjects: { APPLET: { className: "Applet", useSQLite: true } },
-      serviceBindings: {
-        // The lease-backed proxy is a later slice; models are unavailable.
-        CAPABILITIES: async () =>
-          Response.json({ status: "unavailable", reason: "dev" }),
-      },
-      bindings: {
-        APPLET_ID: options.appletId,
-        APPLET_TOKEN: options.token,
-        APPLET_UI: options.html ?? "",
-      },
-      host: "127.0.0.1",
-      port: options.port ?? 0,
-    }),
-  );
-
-  let url: URL;
-  try {
-    url = await bootedWithin(miniflare.ready);
-  } catch (error) {
-    // A runtime that never started is let go of rather than waited on.
-    void miniflare.dispose().catch(() => {});
-    throw error;
-  }
-  return {
-    url,
-    fetch: (path, init) =>
-      miniflare.dispatchFetch(
-        new URL(path, url).toString(),
-        init as never,
-      ) as unknown as Promise<Response>,
-    dispose: () => miniflare.dispose(),
-  };
-}