@frockbot/applet-sdk 0.0.0 → 0.3.13

package/src/cli/new.ts

@@ -0,0 +1,74 @@
+/** `applet new` — the template, with the name filled in. */
+
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { SDK_ROOT } from "./paths.js";
+
+const TEMPLATE_ROOT = join(SDK_ROOT, "template");
+
+/** `Weekly Plan` -> `weekly-plan`. */
+export function appletIdFrom(name: string): string {
+  const id = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32)
+    .replace(/-+$/g, "");
+  if (!/^[a-z][a-z0-9-]{0,31}$/.test(id)) {
+    throw new Error(`"${name}" does not yield a usable Applet id`);
+  }
+  return id;
+}
+
+function fill(text: string, id: string, displayName: string): string {
+  return text
+    .replaceAll("__APPLET_ID__", id)
+    .replaceAll("__APPLET_NAME__", displayName);
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface NewAppletResult {
+  id: string;
+  displayName: string;
+  directory: string;
+  files: string[];
+}
+
+export async function newApplet(options: {
+  name: string;
+  /** Where the Applet directory is created; the durable root in production. */
+  parent: string;
+}): Promise<NewAppletResult> {
+  const id = appletIdFrom(options.name);
+  const directory = join(options.parent, id);
+  if (await exists(directory)) {
+    throw new Error(`${directory} already exists`);
+  }
+  const files: string[] = [];
+  const copy = async (from: string, to: string): Promise<void> => {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from, { withFileTypes: true })) {
+      const source = join(from, entry.name);
+      const target = join(to, entry.name);
+      if (entry.isDirectory()) {
+        await copy(source, target);
+        continue;
+      }
+      const text = await readFile(source, "utf8");
+      await writeFile(target, fill(text, id, options.name), "utf8");
+      files.push(entry.name);
+    }
+  };
+  await copy(TEMPLATE_ROOT, directory);
+  return { id, displayName: options.name, directory, files };
+}

package/src/cli/paths.ts

@@ -0,0 +1,98 @@
+/**
+ * Where the SDK is on disk, and how an Applet's imports resolve to it.
+ *
+ * An Applet lives at a durable root with no `node_modules` of its own — it is
+ * synchronised source, not an npm project — so every specifier it may write is
+ * mapped here, once, and the same map feeds the type checker and the bundler.
+ */
+
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Found by walking up to this package's own `package.json`, not by counting
+ * directories.
+ *
+ * The same module runs from two depths: `src/cli/paths.ts` under Bun, and the
+ * bundled `dist/cli.mjs` under Node on the Computer, which has no Bun. A fixed
+ * `../../` is right for one and silently wrong for the other — it would resolve
+ * the SDK's entries to a directory that does not exist and every Applet import
+ * would fail to type-check with no explanation.
+ */
+function findSdkRoot(): string {
+  let directory = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 6; depth += 1) {
+    try {
+      const manifest = JSON.parse(
+        readFileSync(join(directory, "package.json"), "utf8"),
+      ) as { name?: unknown };
+      if (manifest.name === "@frockbot/applet-sdk") return `${directory}/`;
+    } catch {
+      // Not this directory; keep walking.
+    }
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  throw new Error(
+    "the Applets SDK cannot find its own package root; reinstall @frockbot/applet-sdk",
+  );
+}
+
+/** The installed `@frockbot/applet-sdk` directory. */
+export const SDK_ROOT = findSdkRoot();
+
+export const SDK_ENTRIES = {
+  "@frockbot/applet-sdk/server": join(SDK_ROOT, "src/server/index.ts"),
+  "@frockbot/applet-sdk/client": join(SDK_ROOT, "src/client/index.ts"),
+  "@frockbot/applet-sdk/kit": join(SDK_ROOT, "src/kit/index.tsx"),
+  "@frockbot/applet-sdk/protocol": join(SDK_ROOT, "src/protocol/index.ts"),
+} as const;
+
+/** The ambient declaration of the one Cloudflare module the SDK names. */
+export const SDK_WORKERS_TYPES = join(
+  SDK_ROOT,
+  "types/cloudflare-workers.d.ts",
+);
+
+function packageDirectory(specifier: string): string {
+  return dirname(require.resolve(`${specifier}/package.json`));
+}
+
+/** Node module directories the bundler searches for React and TanStack DB. */
+export function bundlerNodePaths(): string[] {
+  const paths = new Set<string>([join(SDK_ROOT, "node_modules")]);
+  for (const specifier of [
+    "react",
+    "react-dom",
+    "@tanstack/db",
+    "@tanstack/react-db",
+  ]) {
+    try {
+      paths.add(join(packageDirectory(specifier), "..", ".."));
+    } catch {
+      // Resolved through the SDK's own node_modules instead.
+    }
+  }
+  return [...paths];
+}
+
+/** `paths` for the type checker: the SDK's entries plus React's declarations. */
+export function typeCheckerPaths(): Record<string, string[]> {
+  const paths: Record<string, string[]> = {};
+  for (const [specifier, file] of Object.entries(SDK_ENTRIES))
+    paths[specifier] = [file];
+  try {
+    const types = packageDirectory("@types/react");
+    paths.react = [join(types, "index.d.ts")];
+    paths["react/jsx-runtime"] = [join(types, "jsx-runtime.d.ts")];
+    paths["react/*"] = [join(types, "*")];
+  } catch {
+    // No React declarations available; `applet check` reports the import.
+  }
+  return paths;
+}

package/src/cli/runtime.ts

@@ -0,0 +1,123 @@
+/**
+ * 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. `applet dev` serves the page from
+ * it, and `applet build` uses the same runtime to ask the mounted class what
+ * tools it declares rather than guessing from the source.
+ */
+
+import { convertV4MiniflareOptions, Miniflare } from "miniflare";
+
+/** Pinned with the SDK: the runtime an Applet 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,
+    }),
+  );
+
+  const url = await miniflare.ready;
+  return {
+    url,
+    fetch: (path, init) =>
+      miniflare.dispatchFetch(
+        new URL(path, url).toString(),
+        init as never,
+      ) as unknown as Promise<Response>,
+    dispose: () => miniflare.dispose(),
+  };
+}

package/src/client/collections.ts

@@ -0,0 +1,72 @@
+/**
+ * The TanStack DB adapter: one collection per declared table, synced from the
+ * Applet socket and mutated back over it.
+ *
+ * `sync` applies `snapshot` and `changes`; `onInsert`/`onUpdate`/`onDelete`
+ * send one `mutate` frame and return its promise, so an `ack` confirms the
+ * optimistic write and a `reject` rolls it back.
+ */
+
+import { createCollection, type Collection } from "@tanstack/db";
+
+import type { AppletMutationV1 } from "../protocol/index.js";
+import type { AppletTransport } from "./transport.js";
+
+export type AppletRow = Record<string, unknown> & { id: string };
+
+export function createAppletCollection(
+  name: string,
+  transport: AppletTransport,
+): Collection<AppletRow, string> {
+  return createCollection<AppletRow, string>({
+    id: `applet:${name}`,
+    getKey: (row) => row.id,
+    startSync: true,
+    sync: {
+      // The server always sends the whole row on update.
+      rowUpdateMode: "full",
+      sync: ({ begin, write, commit, markReady, truncate }) =>
+        transport.registerTable(name, {
+          begin: () => begin(),
+          write: (message) => {
+            if (message.type === "delete") {
+              write({ type: "delete", key: message.key! });
+              return;
+            }
+            write({ type: message.type, value: message.value as AppletRow });
+          },
+          commit: () => {
+            commit();
+          },
+          markReady,
+          truncate,
+        }),
+    },
+    onInsert: ({ transaction }) =>
+      transport.mutate(
+        transaction.mutations.map((mutation): AppletMutationV1 => ({
+          table: name,
+          op: "insert",
+          key: String(mutation.key),
+          value: mutation.modified as Record<string, unknown>,
+        })),
+      ),
+    onUpdate: ({ transaction }) =>
+      transport.mutate(
+        transaction.mutations.map((mutation): AppletMutationV1 => ({
+          table: name,
+          op: "update",
+          key: String(mutation.key),
+          value: mutation.changes as Record<string, unknown>,
+        })),
+      ),
+    onDelete: ({ transaction }) =>
+      transport.mutate(
+        transaction.mutations.map((mutation): AppletMutationV1 => ({
+          table: name,
+          op: "delete",
+          key: String(mutation.key),
+        })),
+      ),
+  });
+}

package/src/client/index.ts

@@ -0,0 +1,203 @@
+/**
+ * `@frockbot/applet-sdk/client` — everything an Applet's `ui.tsx` imports.
+ *
+ * ```tsx
+ * import { createApplet, newId } from "@frockbot/applet-sdk/client";
+ * import type TodoApplet from "./server";
+ *
+ * const applet = createApplet<TodoApplet>();
+ *
+ * export default function App() {
+ *   const { data: todos } = applet.useLiveQuery((q) =>
+ *     q.from({ t: applet.tables.todos }).orderBy(({ t }) => t.createdAt),
+ *   );
+ * }
+ * ```
+ *
+ * The page never opens the socket itself: the host sends an `init` postMessage
+ * carrying the theme tokens and a short-lived viewer token, and `createApplet`
+ * connects from that. `connect(init)` is the same path, called by hand, which
+ * is what `applet dev` and the tests use.
+ */
+
+import type { Collection } from "@tanstack/db";
+import { useLiveQuery } from "@tanstack/react-db";
+import { useSyncExternalStore, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+
+import type { RowOf, TablesShape } from "../schema/index.js";
+import { createAppletCollection, type AppletRow } from "./collections.js";
+import {
+  AppletTransport,
+  type AppletInitV1,
+  type AppletState,
+  type AppletStatus,
+  type AppletTransportOptions,
+} from "./transport.js";
+
+export type {
+  AppletInitV1,
+  AppletState,
+  AppletStatus,
+  AppletSocket,
+  AppletSocketFactory,
+  AppletTransportOptions,
+} from "./transport.js";
+export { AppletTransport } from "./transport.js";
+export { useLiveQuery } from "@tanstack/react-db";
+export { eq, gt, gte, ilike, like, lt, lte, not, or, and } from "@tanstack/db";
+
+/** A fresh row key. Client inserts must carry one; server inserts need not. */
+export function newId(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Render the Applet. The SDK owns this so an Applet never imports `react-dom`
+ * — one fewer specifier to remember, and the linter can keep the import list
+ * to three entries.
+ */
+export function mount(element: ReactNode): void {
+  const existing = document.getElementById("applet-root");
+  const container =
+    existing ?? document.body.appendChild(document.createElement("div"));
+  createRoot(container).render(element);
+}
+
+export type AppletCollections<TTables extends TablesShape> = {
+  [K in keyof TTables]: Collection<RowOf<TTables[K]> & AppletRow, string>;
+};
+
+export interface AppletClient<TTables extends TablesShape> {
+  /** One TanStack DB collection per declared table, created on first access. */
+  readonly tables: AppletCollections<TTables>;
+  readonly useLiveQuery: typeof useLiveQuery;
+  /** Connection status, viewer identity, and the mounted generation. */
+  useApplet(): AppletState;
+  /** Open the socket by hand; the host's `init` message does this for you. */
+  connect(init: AppletInitV1): void;
+  close(): void;
+}
+
+export interface CreateAppletOptions extends AppletTransportOptions {
+  /**
+   * Listen for the host's `init` postMessage and connect from it.
+   * Defaults to true in a browser and false anywhere else.
+   */
+  autoConnect?: boolean;
+}
+
+/** The host's `init`, with the fields an Applet page needs. */
+export interface AppletHostInitV1 {
+  themeTokens: Record<string, string>;
+  applet: AppletInitV1;
+}
+
+function decodeHostInit(data: unknown): AppletHostInitV1 | undefined {
+  if (!data || typeof data !== "object") return undefined;
+  const message = data as Record<string, unknown>;
+  if (message.schemaVersion !== 1 || message.type !== "init") return undefined;
+  const applet = message.applet;
+  const tokens = message.themeTokens;
+  if (!applet || typeof applet !== "object") return undefined;
+  if (!tokens || typeof tokens !== "object") return undefined;
+  const value = applet as Record<string, unknown>;
+  if (
+    typeof value.socketUrl !== "string" ||
+    typeof value.token !== "string" ||
+    typeof value.generationId !== "string"
+  ) {
+    return undefined;
+  }
+  const themeTokens: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(
+    tokens as Record<string, unknown>,
+  )) {
+    if (typeof entry === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(key)) {
+      themeTokens[key] = entry;
+    }
+  }
+  return {
+    themeTokens,
+    applet: {
+      socketUrl: value.socketUrl,
+      token: value.token,
+      generationId: value.generationId,
+    },
+  };
+}
+
+/** Paint the host's semantic tokens onto the page as `--frockbot-*`. */
+export function applyThemeTokens(tokens: Record<string, string>): void {
+  if (typeof document === "undefined") return;
+  for (const [name, value] of Object.entries(tokens)) {
+    document.documentElement.style.setProperty(`--frockbot-${name}`, value);
+  }
+}
+
+/** Subscribe to the host's `init` message. Returns an unsubscribe function. */
+export function listenForAppletInit(
+  handler: (init: AppletHostInitV1) => void,
+): () => void {
+  if (typeof window === "undefined") return () => {};
+  const listener = (event: MessageEvent) => {
+    if (event.source !== window.parent) return;
+    const init = decodeHostInit(event.data);
+    if (init) handler(init);
+  };
+  window.addEventListener("message", listener);
+  return () => window.removeEventListener("message", listener);
+}
+
+export function createApplet<TServer extends { tables: TablesShape }>(
+  options: CreateAppletOptions = {},
+): AppletClient<TServer["tables"]> {
+  const { autoConnect, ...transportOptions } = options;
+  const transport = new AppletTransport(transportOptions);
+  const collections = new Map<string, Collection<AppletRow, string>>();
+
+  const tables = new Proxy({} as Record<string, unknown>, {
+    get(_target, property) {
+      if (typeof property !== "string") return undefined;
+      let collection = collections.get(property);
+      if (!collection) {
+        collection = createAppletCollection(property, transport);
+        collections.set(property, collection);
+      }
+      return collection;
+    },
+    has: () => true,
+    ownKeys: () => [...collections.keys()],
+    getOwnPropertyDescriptor: () => ({ enumerable: true, configurable: true }),
+  }) as AppletCollections<TServer["tables"]>;
+
+  if (autoConnect ?? typeof window !== "undefined") {
+    let lastInit: AppletInitV1 | undefined;
+    listenForAppletInit((init) => {
+      applyThemeTokens(init.themeTokens);
+      lastInit = init.applet;
+      transport.connect(init.applet);
+    });
+    // Leave with a close frame rather than a dropped connection: the server
+    // then sees a 1000, not a 1006 it has to discover on its next write. A
+    // page restored from the back/forward cache reconnects with the same
+    // token; a stale one is answered with a reload by the host.
+    window.addEventListener("pagehide", () => transport.close());
+    window.addEventListener("pageshow", (event) => {
+      if (event.persisted && lastInit) transport.connect(lastInit);
+    });
+  }
+
+  return {
+    tables,
+    useLiveQuery,
+    useApplet: () =>
+      useSyncExternalStore(
+        (listener) => transport.subscribe(listener),
+        () => transport.state,
+        () => transport.state,
+      ),
+    connect: (init) => transport.connect(init),
+    close: () => transport.close(),
+  };
+}