@frockbot/applet-sdk 0.7.178 → 0.7.180

package/README.md

@@ -1,113 +1,97 @@
 # @frockbot/applet-sdk
 
-The SDK a FrockBot Applet is written against: a schema-first Durable Object
-server, a TanStack DB client over one real-time socket, a precompiled component
-kit on the theme tokens, a linter, and the build pipeline the cloud build
-service runs.
-
-An Applet is authored with the `applet_*` tools, built by `apps/applet-build`,
-and mounted as a Durable Object facet from an immutable artifact. There is no
-CLI: nothing outside the service builds an Applet, and no Computer is involved
-at any point.
+What a FrockBot Plugin is written against, and the build that turns a
+Plugin's source into the module and manifest a publish stores (ADR 0026).
 
 ## Entry points
 
-| Import                              | For                                                                  |
-| ----------------------------------- | -------------------------------------------------------------------- |
-| `@frockbot/applet-sdk/server`       | `Applet`, `table`, `t` — the Applet's `server.ts`                    |
-| `@frockbot/applet-sdk/client`       | `createApplet`, `mount`, `newId` — the Applet's `ui.tsx`             |
-| `@frockbot/applet-sdk/kit`          | the fourteen components (`src/kit/README.md`)                        |
-| `@frockbot/applet-sdk/lint`         | the flat ESLint config and the five custom rules                     |
-| `@frockbot/applet-sdk/protocol`     | wire protocol v1, for the kernel and for tests                       |
-| `@frockbot/applet-sdk/build`        | `runAppletBuildV1` — the five stages, for the service                |
-| `@frockbot/applet-sdk/plugin`       | types only: `PluginModule`, `PluginContext` — a Plugin's `plugin.ts` |
-| `@frockbot/applet-sdk/build/plugin` | `runPluginBuildV1` — the four Plugin stages, for the service         |
+| Import                              | For                                                                                        |
+| ----------------------------------- | ------------------------------------------------------------------------------------------ |
+| `@frockbot/applet-sdk/plugin`       | types only: `PluginModule`, `PluginContext` and the rest — a Plugin's `plugin.ts`          |
+| `@frockbot/applet-sdk/build/plugin` | `runPluginBuildV1` — the four stages, for the build service and the seeded Plugins' script |
+
+## A Plugin
+
+A Plugin is a directory: a `plugin.json` descriptor, a `plugin.ts` module,
+and any `.ts` files beside it that the module imports. `plugin.ts` has no
+default export. It exports `tools` and `execute` by name, and may export
+`hooks`, `services`, `triggers`, `views`, `cards` and `modelProviders`
+(`PluginModule`). `tools` may be empty: a Plugin that only serves hooks
+builds.
+
+`@frockbot/applet-sdk/plugin` is declarations only, so it is imported with
+`import type`; a value import of it fails the bundle stage.
+`app/plugins/sdk-types.test.ts` pins its `PluginContext`, hook events, grants
+and hook payloads to the kernel's own types, so a Plugin that type-checks
+here sees the `ctx` the kernel builds.
+
+A model provider (`PluginModelProvider`, ADR 0032) answers a normalized model
+request with normalized stream events, and makes its one upstream call
+through `ctx.modelTransport`. The deployment serves a provider only from the
+artifact its own provider catalog names, so this is not a way for a
+Bot-written Plugin to reach a provider.
+
+`plugin/template/` is the scaffold a new Plugin starts as, with
+`__PLUGIN_ID__` and `__PLUGIN_NAME__` for `plugin_create` to fill in.
+`scripts/build-applets-assets.ts` carries it into the Worker as
+`app/plugins/template.generated.ts`, and carries `plugin/index.d.ts` into the
+Plugins Skill as `app/plugins/skills/plugins/references/types.md`.
 
 ## The build
 
-`runAppletBuildV1(directory, { mode })` is five named stages over one
-directory: `descriptor`, `typecheck`, `lint`, `bundle`, `describe`. `check`
-stops after the linter; `build` goes on to the artifacts. A stage that fails
-stops the run and names itself, and every failure is a list of
-`{file, line, column, message, severity}`.
-
-`manifest.json`'s tool declarations are derived by mounting the built
-`server.js` in Miniflare and calling `health()` — the same question the kernel
-asks the facet before it admits a generation, so the manifest cannot disagree
-with the code.
-
-`template/` is the scaffold a new Applet starts as.
-`scripts/build-applets-assets.ts` turns it into `applets/template.generated.ts`,
-which `applet_create` writes through the Workspace.
-
-## Plugins
-
-A Plugin (ADR 0026) is written against `@frockbot/applet-sdk/plugin`, which
-is declarations only: `plugin.ts` exports `tools` and `execute`, and may
-export `hooks`, `services`, `triggers`, `views` and `modelProviders`, beside a `plugin.json` descriptor.
-`tools` may be empty — a Plugin that only serves hooks is admissible, because
-the kernel's own descriptor contract admits one. A model provider
-(`PluginModelProvider`, ADR 0032) answers a normalized model request with
-normalized stream events and makes its one upstream call through
-`ctx.modelTransport`; the deployment serves it only from the artifact its own
-provider catalog names, so this is not a way for a Bot-written Plugin to reach
-a provider.
-`runPluginBuildV1(directory, { mode, id })` is four stages — `descriptor`,
-`typecheck`, `bundle`, `describe` — with no lint stage, because a Plugin's
-reach is a grant the descriptor declares and the kernel enforces. The bundle
-is one ESM module with every import inlined, and the manifest is read by
-running that module in Miniflare with no outbound network. `plugin/template/`
-is the scaffold a new Plugin starts as. `PluginContext` is held to the
-kernel's own `ctx` keys by `app/plugins/sdk-types.test.ts`.
-
-## What runs where
-
-`server.ts` becomes a single ESM file whose only import is `cloudflare:workers`,
-loaded by the kernel's `APPLETS` Worker Loader with no outbound network, and
-mounted as a facet under `AppletState`. `ui.tsx` becomes one self-contained HTML
-page served from the anonymous artifact origin into a sandboxed iframe, which
-receives its theme tokens and a short-lived viewer token through the host's
-`init` message and opens exactly one WebSocket back to the facet.
-
-The Cloudflare programming model is not hidden: an Applet is a Durable Object
-with SQLite and hibernating sockets. What the SDK does hide is every binding
-name — an author sees `tables`, `tools`, and `this.db`.
-
-## Wire protocol
-
-JSON frames, at most 64 KB each, decoded by `src/protocol/` at both ends;
-an unknown type, field, or table fails closed. Two versions are spoken on the
-same server, told apart by the socket URL: a page built against v2 opens with
-`v=2`, and a page built before it opens with nothing and is spoken to in v1.
-
-| Direction       | Frame      | Carries                                                                                     |
-| --------------- | ---------- | ------------------------------------------------------------------------------------------- |
-| server → client | `hello`    | contract, generationId, viewer, tables, revision, cursor — and in v2, the `snapshot` itself |
-| client → server | `hello`    | contract, optional `since` cursor for catch-up; in v2 only on a resume or when asked        |
-| server → client | `snapshot` | every row of every table, plus the cursor                                                   |
-| server → client | `changes`  | ordered row changes, optionally tagged with a client txn id                                 |
-| client → server | `mutate`   | one client transaction: insert/update/delete                                                |
-| server → client | `ack`      | the resulting rows for that txn                                                             |
-| server → client | `reject`   | why the txn was refused (the client rolls back)                                             |
-
-The host hands the page its credential in an `init` postMessage, and a fresh
-credential later in a `refresh` of the same shape; the page reconnects in
-place rather than being reloaded, and with its cursor on the URL that is the
-`changes` path.
-
-A v2 page's first render waits on one frame: the server's `hello` carries the
-snapshot when the URL named no `since` cursor, and the page marks its
-collections ready on it. A reconnect puts `since` on the URL, gets a plain
-`hello`, and asks for `changes` as v1 does. A snapshot that would not fit the
-frame is left out of the hello and the v1 exchange follows.
+`runPluginBuildV1(directory, { mode, id })` is four named stages over one
+directory. A stage that fails stops the run and names itself, with a list of
+`{file, line, column, message, severity}` diagnostics. `check` stops after
+the type checker; `build` goes on to the module and its manifest.
+
+1. `descriptor`: `plugin.json` is a JSON object whose `id` matches
+   `/^[a-z][a-z0-9-]{0,63}$/` and, when the caller passes `id`, is that id.
+   The build reads nothing else from it. The app Worker decodes the full
+   descriptor and refuses a publish whose descriptor and manifest disagree
+   (`pluginManifestDisagreementV1` in `app/plugins/authoring.ts`).
+2. `typecheck`: every `.ts` file in the directory, strict, against ES2022
+   and the DOM lib for `fetch`, `Request` and `Response`, with
+   `@frockbot/applet-sdk/plugin` resolved to `plugin/index.d.ts`. The
+   directory must hold a `plugin.ts`. Only errors fail the stage.
+3. `bundle`: esbuild makes one unminified ESM module with every import
+   inlined. Nothing is external, so a specifier the bundler cannot inline
+   fails here, not at mount. `module-paths.ts` rewrites esbuild's module-path
+   comments relative to the Plugin's directory, so the same source builds to
+   the same bytes wherever it is built.
+4. `describe`: the bundle runs in Miniflare beside a describing Worker, with
+   no bindings and no outbound network: every `fetch` is answered with a 403.
+   Import-time code runs inside workerd, never in the build's own process.
+   What the module exports is the manifest. `tools` must be an array and
+   `execute` a function; each tool needs a name matching
+   `/^[a-z][a-z0-9_]{0,63}$/` and a description; `hooks`, `triggers` and
+   `views` hold functions, `services` any values, each card a `render` and
+   each model provider a `stream`. A Plugin declares at most 64 tools, each
+   name once.
+
+Each describe spawns its own workerd, and `boot.ts` bounds the boot. A
+runtime that is not ready within `BOOT_DEADLINE_MS` (30 seconds), or whose
+spawn fails outright, is a `RuntimeDidNotStart`. The build lets that runtime
+go rather than waiting on it and boots once more; if the second boot does not
+come up either, the stage fails with that as its diagnostic.
+
+A build answers the module text and its manifest:
+`{ contract: 1, tools, hooks, services, triggers, views, cards, modelProviders, hashes: { module } }`,
+where `hashes.module` is the SHA-256 of the module.
+
+Two callers run it. The build service in `apps/applet-build` runs `check`
+for `plugin_check` and `build` for `plugin_publish`.
+`scripts/build-seeded-plugins.ts` builds each Plugin under
+`app/plugins/seeded/` into the Worker bundle through the same stages.
 
 ## Tests
 
 ```sh
-bun test test spike
+bun run test
 ```
 
-Pure modules and the client are tested in `bun test`: the store runs against
-`bun:sqlite`, and `test/loopback.ts` joins the real protocol server to the real
-client transport through a pair of fake sockets. `test/build.test.ts` and
-`spike/` run the real pipeline and the built Applet in Miniflare.
+`test/plugin-build.test.ts` runs `runPluginBuildV1` over the real template,
+which `test/plugin-scaffold.ts` fills in and writes to a temporary directory.
+It covers each stage's failure and diagnostics, identical module bytes from
+different and symlinked roots, and the manifest read off each kind of export.
+Every build test boots workerd through Miniflare, so a run needs to bind a
+local port. The root `bun test` runs this file too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.178",
+  "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

@@ -1,6 +1,5 @@
 /**
- * The Plugin build (ADR 0026): four named stages over one directory, sharing
- * the Applet build's type checker, bundler and Miniflare boot.
+ * The Plugin build (ADR 0026): four named stages over one directory.
  *
  *  1. `descriptor` — `plugin.json` parses and names the Plugin the caller
  *     asked for. Nothing more is decided here: the app Worker holds the full
@@ -29,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";
 
@@ -348,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(
@@ -368,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", {
@@ -378,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;
@@ -393,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(),
-  };
-}