@frockbot/applet-sdk 0.7.150 → 0.7.151

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.150",
+  "version": "0.7.151",
   "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.",
   "license": "UNLICENSED",
   "exports": {
-    "./server": "./src/server/index.ts",
-    "./client": "./src/client/index.ts",
-    "./kit": "./src/kit/index.tsx",
     "./lint": "./src/lint/index.ts",
-    "./protocol": "./src/protocol/index.ts",
-    "./build": "./src/build/pipeline.ts",
     "./build/plugin": "./src/build/plugin.ts",
     "./plugin": "./plugin/index.d.ts",
     "./package.json": "./package.json"

package/src/build/runtime.ts

@@ -12,7 +12,7 @@ import { convertV4MiniflareOptions, Miniflare } from "miniflare";
 
 import { bootedWithin } from "./boot.js";
 
-/** Pinned with the SDK: the runtime an Applet is checked against. */
+/** Pinned with the SDK: the runtime a Plugin build is checked against. */
 export const APPLET_COMPATIBILITY_DATE = "2026-08-27";
 
 /**

package/src/build/artifacts.ts

@@ -1,200 +0,0 @@
-/**
- * Three immutable artifacts from two source files.
- *
- * `server.js`      one ESM file whose only import is `cloudflare:workers`,
- *                  exporting `Applet`, which is the name the kernel mounts.
- * `ui.html`        one self-contained page: React, TanStack DB, the kit, and
- *                  the app inlined. No external URL, because the artifact
- *                  origin serves it into a sandbox with no network of its own.
- * `manifest.json`  `{ contract, tools, hashes }`.
- *
- * The tool declarations come from mounting the built server in Miniflare and
- * calling `health()`, not from reading the source. Static analysis would be a
- * second implementation of `this.tool(...)` that could disagree with the one
- * the kernel actually asks — and the kernel admits a generation by comparing
- * the manifest to the facet's own `health()`, so any disagreement is a failed
- * publish. Running the code is the only derivation that cannot drift.
- *
- * Nothing here touches a filesystem beyond the source it is given: the build
- * service returns these three strings over its contract, and the app stores
- * them under their content hashes.
- */
-
-import { createHash, randomUUID } from "node:crypto";
-
-import { build as esbuild } from "esbuild";
-
-import type { AppletDescriptionV1 } from "../server/applet.js";
-import { readDescriptor, type AppletBuildManifestV1 } from "./manifest.js";
-import { stableModulePaths } from "./module-paths.js";
-import { bundlerNodePaths, SDK_ENTRIES, SDK_ROOT } from "./paths.js";
-import { withOneMoreBoot } from "./boot.js";
-import { startAppletRuntime } from "./runtime.js";
-
-export interface AppletArtifactsV1 {
-  manifest: AppletBuildManifestV1;
-  server: string;
-  ui: string;
-}
-
-function sha256(text: string): string {
-  return createHash("sha256").update(text, "utf8").digest("hex");
-}
-
-async function bundle(options: {
-  stdin: string;
-  resolveDir: string;
-  platform: "neutral" | "browser";
-  format: "esm" | "iife";
-  external: string[];
-  minify: boolean;
-  loaderName: string;
-}): Promise<string> {
-  const result = await esbuild({
-    stdin: {
-      contents: options.stdin,
-      resolveDir: options.resolveDir,
-      sourcefile: options.loaderName,
-      loader: "tsx",
-    },
-    bundle: true,
-    write: false,
-    format: options.format,
-    platform: options.platform,
-    target: "es2022",
-    jsx: "automatic",
-    minify: options.minify,
-    legalComments: "none",
-    external: options.external,
-    alias: { ...SDK_ENTRIES },
-    nodePaths: bundlerNodePaths(),
-    conditions: ["import", "module", "browser", "default"],
-    define: { "process.env.NODE_ENV": '"production"' },
-    metafile: true,
-    logLevel: "silent",
-  });
-  const file = result.outputFiles?.[0];
-  if (!file) throw new Error("The bundler produced no output");
-  return stableModulePaths(file.text, result.metafile, options.resolveDir, [
-    { directory: SDK_ROOT, prefix: "applet-sdk/" },
-  ]);
-}
-
-function page(title: string, script: string): string {
-  // Nothing is fetched: the CSP on the artifact origin blocks every external
-  // request, so React, the kit, and the app are all in this one <script>.
-  return [
-    "<!doctype html>",
-    '<html lang="en">',
-    "<head>",
-    '<meta charset="utf-8">',
-    '<meta name="viewport" content="width=device-width, initial-scale=1">',
-    `<title>${title.replaceAll("<", "&lt;")}</title>`,
-    // The root gets a definite height so the kit's own root (min-height: 100%)
-    // fills the page; without it an Applet ends where its content ends.
-    "<style>html,body,#applet-root{margin:0;height:100%;background:var(--frockbot-surface,#ffffff)}</style>",
-    "</head>",
-    "<body>",
-    '<div id="applet-root"></div>',
-    `<script>${script}</script>`,
-    "</body>",
-    "</html>",
-  ].join("\n");
-}
-
-/**
- * Ask the built module what it declares, by running it. A boot that never
- * reports ready is tried once more (`boot.ts`) before the build gives up.
- */
-export function readDescription(
-  serverCode: string,
-  appletId: string,
-): Promise<AppletDescriptionV1> {
-  return withOneMoreBoot(() => describeInRuntime(serverCode, appletId));
-}
-
-async function describeInRuntime(
-  serverCode: string,
-  appletId: string,
-): Promise<AppletDescriptionV1> {
-  const runtime = await startAppletRuntime({
-    serverCode,
-    appletId,
-    token: randomUUID(),
-  });
-  try {
-    // `health()` first: it is what the kernel calls, so a server that cannot
-    // mount fails here the way it would fail a publish.
-    const health = await runtime.fetch("/health");
-    if (!health.ok) {
-      throw new Error(`The Applet failed to mount: ${await health.text()}`);
-    }
-    const response = await runtime.fetch("/describe");
-    if (!response.ok) {
-      throw new Error(
-        `The Applet could not describe its tools: ${await response.text()}`,
-      );
-    }
-    return (await response.json()) as AppletDescriptionV1;
-  } finally {
-    await runtime.dispose();
-  }
-}
-
-/** The two bundles, in the order that lets a bundle failure precede a boot. */
-export async function bundleAppletArtifacts(
-  directory: string,
-): Promise<{ descriptorId: string; server: string; ui: string }> {
-  const descriptor = await readDescriptor(directory);
-  const server = await bundle({
-    // `Applet` is the export name the kernel's facet mount looks up; the author
-    // writes an ordinary default export and never learns that name.
-    stdin:
-      'import AppletClass from "./server";\nexport { AppletClass as Applet };\n',
-    resolveDir: directory,
-    platform: "neutral",
-    format: "esm",
-    external: ["cloudflare:workers"],
-    minify: false,
-    loaderName: "applet-server-entry.ts",
-  });
-  const uiScript = await bundle({
-    stdin: 'import "./ui";\n',
-    resolveDir: directory,
-    platform: "browser",
-    format: "iife",
-    external: [],
-    minify: true,
-    loaderName: "applet-ui-entry.tsx",
-  });
-  return {
-    descriptorId: descriptor.id,
-    server,
-    ui: page(descriptor.displayName, uiScript),
-  };
-}
-
-/** The manifest for artifacts whose declarations have been read. */
-export function appletManifest(
-  tools: AppletDescriptionV1["tools"],
-  artifacts: { server: string; ui: string },
-): AppletBuildManifestV1 {
-  return {
-    contract: 1,
-    tools,
-    hashes: { server: sha256(artifacts.server), ui: sha256(artifacts.ui) },
-  };
-}
-
-/** Bundle, boot, describe. The whole artifact derivation, with no output. */
-export async function buildAppletArtifacts(
-  directory: string,
-): Promise<AppletArtifactsV1> {
-  const { descriptorId, server, ui } = await bundleAppletArtifacts(directory);
-  const description = await readDescription(server, descriptorId);
-  return {
-    manifest: appletManifest(description.tools, { server, ui }),
-    server,
-    ui,
-  };
-}

package/src/build/check.ts

@@ -1,135 +0,0 @@
-/**
- * The check stage — the type checker and the linter, one diagnostic list.
- *
- * The Applet has no `node_modules`: it is source at a durable root. So the
- * compiler options are built here from `paths.ts` rather than from a tsconfig
- * the Bot would have to maintain, and every diagnostic comes back in the one
- * shape the CLI prints.
- */
-
-import { readdir } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
-
-import ts from "typescript";
-
-import { lintApplet, type AppletDiagnostic } from "../lint/index.js";
-import { readDescriptor } from "./manifest.js";
-import { SDK_WORKERS_TYPES, typeCheckerPaths } from "./paths.js";
-
-const COMPILER_OPTIONS: ts.CompilerOptions = {
-  target: ts.ScriptTarget.ES2022,
-  module: ts.ModuleKind.ESNext,
-  moduleResolution: ts.ModuleResolutionKind.Bundler,
-  jsx: ts.JsxEmit.ReactJSX,
-  strict: true,
-  noEmit: true,
-  skipLibCheck: true,
-  esModuleInterop: true,
-  allowSyntheticDefaultImports: true,
-  forceConsistentCasingInFileNames: true,
-  lib: ["lib.es2022.d.ts", "lib.dom.d.ts"],
-  types: [],
-};
-
-async function appletSources(directory: string): Promise<string[]> {
-  const found: string[] = [];
-  const walk = async (current: string): Promise<void> => {
-    for (const entry of await readdir(current, { withFileTypes: true })) {
-      if (entry.name === "node_modules" || entry.name === "dist") continue;
-      if (entry.name.startsWith(".")) continue;
-      const path = join(current, entry.name);
-      if (entry.isDirectory()) await walk(path);
-      else if (/\.(ts|tsx)$/.test(entry.name)) found.push(path);
-    }
-  };
-  await walk(directory);
-  return found;
-}
-
-/** Type-check the Applet against the SDK's declarations. */
-export async function typeCheckApplet(
-  directory: string,
-): Promise<AppletDiagnostic[]> {
-  const root = resolve(directory);
-  const files = await appletSources(root);
-  if (files.length === 0) {
-    return [
-      {
-        file: "applet.json",
-        line: 1,
-        column: 1,
-        message:
-          "No TypeScript sources found; an Applet needs server.ts and ui.tsx.",
-        severity: "error",
-      },
-    ];
-  }
-  // No `baseUrl`: TypeScript 7 rejects it, and it was never needed — every
-  // mapping `typeCheckerPaths()` returns is already an absolute path.
-  const program = ts.createProgram([...files, SDK_WORKERS_TYPES], {
-    ...COMPILER_OPTIONS,
-    paths: typeCheckerPaths(),
-  });
-  return ts
-    .getPreEmitDiagnostics(program)
-    .filter(
-      (diagnostic) =>
-        !diagnostic.file || diagnostic.file.fileName.startsWith(root),
-    )
-    .map((diagnostic) => {
-      const message = ts.flattenDiagnosticMessageText(
-        diagnostic.messageText,
-        " ",
-      );
-      if (!diagnostic.file || diagnostic.start === undefined) {
-        return {
-          file: "applet.json",
-          line: 1,
-          column: 1,
-          message,
-          severity: "error" as const,
-        };
-      }
-      const position = diagnostic.file.getLineAndCharacterOfPosition(
-        diagnostic.start,
-      );
-      return {
-        file: relative(root, diagnostic.file.fileName),
-        line: position.line + 1,
-        column: position.character + 1,
-        message: `${message} (TS${diagnostic.code})`,
-        severity:
-          diagnostic.category === ts.DiagnosticCategory.Error
-            ? ("error" as const)
-            : ("warning" as const),
-      };
-    });
-}
-
-/** Everything the check stage reports, in source order. */
-export async function checkApplet(
-  directory: string,
-): Promise<AppletDiagnostic[]> {
-  const root = resolve(directory);
-  const diagnostics: AppletDiagnostic[] = [];
-  try {
-    await readDescriptor(root);
-  } catch (error) {
-    diagnostics.push({
-      file: "applet.json",
-      line: 1,
-      column: 1,
-      message: error instanceof Error ? error.message : String(error),
-      severity: "error",
-    });
-    return diagnostics;
-  }
-  diagnostics.push(...(await typeCheckApplet(root)));
-  diagnostics.push(...(await lintApplet(root)));
-  return diagnostics.sort(
-    (left, right) =>
-      left.file.localeCompare(right.file) ||
-      left.line - right.line ||
-      left.column - right.column,
-  );
-}

package/src/build/manifest.ts

@@ -1,56 +0,0 @@
-/** `applet.json`: the three facts the SDK needs before it reads any code. */
-
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-
-import { APPLET_CONTRACT_VERSION } from "../protocol/index.js";
-import type { AppletToolDeclarationV1 } from "../server/applet.js";
-
-export interface AppletDescriptorV1 {
-  /** `/^[a-z][a-z0-9-]{0,31}$/`; the scaffold's directory name. */
-  id: string;
-  displayName: string;
-  contract: 1;
-}
-
-export interface AppletBuildManifestV1 {
-  contract: 1;
-  tools: AppletToolDeclarationV1[];
-  hashes: { server: string; ui: string };
-}
-
-export function decodeDescriptor(input: unknown): AppletDescriptorV1 {
-  if (!input || typeof input !== "object")
-    throw new Error("applet.json must be an object");
-  const value = input as Record<string, unknown>;
-  const id = value.id;
-  if (typeof id !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(id)) {
-    throw new Error('applet.json "id" must match /^[a-z][a-z0-9-]{0,31}$/');
-  }
-  if (
-    typeof value.displayName !== "string" ||
-    value.displayName.length === 0 ||
-    value.displayName.length > 64
-  ) {
-    throw new Error('applet.json "displayName" must be 1-64 characters');
-  }
-  if (value.contract !== APPLET_CONTRACT_VERSION) {
-    throw new Error(
-      `applet.json "contract" must be ${APPLET_CONTRACT_VERSION}`,
-    );
-  }
-  return { id, displayName: value.displayName, contract: 1 };
-}
-
-export async function readDescriptor(
-  directory: string,
-): Promise<AppletDescriptorV1> {
-  const path = join(directory, "applet.json");
-  let text: string;
-  try {
-    text = await readFile(path, "utf8");
-  } catch {
-    throw new Error(`No applet.json in ${directory}`);
-  }
-  return decodeDescriptor(JSON.parse(text));
-}

package/src/build/pipeline.ts

@@ -1,96 +0,0 @@
-/**
- * The whole Applet build, as five named stages over one directory.
- *
- * `applet_check` and `applet_publish` are the two ways in, and both reach
- * these stages through the same build service. There is one implementation of
- * each stage, so a check and the publish that follows it cannot disagree about
- * whether the code is admissible or about what it hashes to.
- *
- * A stage that fails stops the run and names itself, which is what turns a
- * wall of diagnostics into "your `server.ts` does not type-check". The two
- * stages that produce no diagnostic list of their own — `bundle` and
- * `describe` — report the thrown message as one diagnostic against
- * `applet.json`, so a caller has one shape to render.
- */
-
-import { lintApplet, type AppletDiagnostic } from "../lint/index.js";
-import { buildAppletArtifacts, type AppletArtifactsV1 } from "./artifacts.js";
-import { typeCheckApplet } from "./check.js";
-import { readDescriptor } from "./manifest.js";
-
-export type AppletBuildStage =
-  "descriptor" | "typecheck" | "lint" | "bundle" | "describe";
-
-export type AppletBuildOutcome =
-  | { status: "checked" }
-  | ({ status: "built" } & AppletArtifactsV1)
-  | {
-      status: "failed";
-      stage: AppletBuildStage;
-      diagnostics: AppletDiagnostic[];
-    };
-
-/** A thrown stage failure, reported at `applet.json` for want of a position. */
-function thrown(error: unknown): AppletDiagnostic[] {
-  return [
-    {
-      file: "applet.json",
-      line: 1,
-      column: 1,
-      message: error instanceof Error ? error.message : String(error),
-      severity: "error",
-    },
-  ];
-}
-
-function hasError(diagnostics: AppletDiagnostic[]): boolean {
-  return diagnostics.some((diagnostic) => diagnostic.severity === "error");
-}
-
-export interface AppletBuildPipelineOptions {
-  /** `check` stops after the linter; `build` goes on to the artifacts. */
-  mode: "check" | "build";
-}
-
-export async function runAppletBuildV1(
-  directory: string,
-  options: AppletBuildPipelineOptions,
-): Promise<AppletBuildOutcome> {
-  try {
-    await readDescriptor(directory);
-  } catch (error) {
-    return {
-      status: "failed",
-      stage: "descriptor",
-      diagnostics: thrown(error),
-    };
-  }
-
-  const types = await typeCheckApplet(directory);
-  if (hasError(types)) {
-    return { status: "failed", stage: "typecheck", diagnostics: types };
-  }
-  const lint = await lintApplet(directory);
-  if (hasError(lint)) {
-    return { status: "failed", stage: "lint", diagnostics: lint };
-  }
-  if (options.mode === "check") return { status: "checked" };
-
-  let artifacts: AppletArtifactsV1;
-  try {
-    artifacts = await buildAppletArtifacts(directory);
-  } catch (error) {
-    // `describe` is the only stage that boots the built module, and both of
-    // its failures say so in their own words; anything else thrown here came
-    // out of the bundler.
-    const message = error instanceof Error ? error.message : String(error);
-    return {
-      status: "failed",
-      stage: /^The Applet (failed to mount|could not describe)/.test(message)
-        ? "describe"
-        : "bundle",
-      diagnostics: thrown(error),
-    };
-  }
-  return { status: "built", ...artifacts };
-}

package/src/client/collections.ts

@@ -1,72 +0,0 @@
-/**
- * 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),
-        })),
-      ),
-  });
-}