@frockbot/applet-sdk 0.7.179 → 0.7.181

package/README.md

@@ -68,11 +68,11 @@ the type checker; `build` goes on to the module and its manifest.
    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.
+Each describe spawns its own workerd, and both ends of its life are bounded
+so a build answers rather than hangs: a runtime not ready within
+`BOOT_DEADLINE_MS` (30 seconds) fails the stage with that as its diagnostic,
+and the teardown, awaited on every path, gets `DISPOSE_DEADLINE_MS`
+(10 seconds).
 
 A build answers the module text and its manifest:
 `{ contract: 1, tools, hooks, services, triggers, views, cards, modelProviders, hashes: { module } }`,

package/package.json

@@ -1,39 +1,28 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.179",
+  "version": "0.7.181",
   "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.",
+  "description": "Authoring SDK for FrockBot Plugins: the declarations a Plugin is written against, and the build pipeline the cloud build service runs.",
   "license": "UNLICENSED",
   "exports": {
-    "./lint": "./src/lint/index.ts",
     "./build/plugin": "./src/build/plugin.ts",
     "./plugin": "./plugin/index.d.ts",
     "./package.json": "./package.json"
   },
   "files": [
     "src",
-    "types",
-    "template",
     "plugin",
     "README.md"
   ],
   "scripts": {
-    "test": "bun test test spike",
+    "test": "bun test test",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@tanstack/db": "0.8.7",
-    "@tanstack/react-db": "0.3.7",
-    "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.7",
     "esbuild": "0.28.2",
-    "eslint": "10.10.0",
     "miniflare": "5.20260828.0-alpha",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
-    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
-    "typescript-eslint": "8.69.0"
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2"
   },
   "devDependencies": {
     "@types/bun": "1.4.1",

package/plugin/index.d.ts

@@ -3,10 +3,11 @@
  * against (ADR 0026).
  *
  * A Plugin is one ESM module with no imports of its own. It exports `tools`
- * and `execute`, and may export `hooks`, `services` and `triggers`. The
- * kernel's generated index imports the built module, checks these exports
- * against the Plugin's `plugin.json` once at mount, and hands every call a
- * narrow `ctx` naming only what that Plugin declared it may do.
+ * and `execute`, and may export `hooks`, `services`, `triggers`, `views`,
+ * `cards` and `modelProviders` (`PluginModule`). The kernel's generated index
+ * imports the built module, checks these exports against the Plugin's
+ * `plugin.json` once at mount, and hands every call a narrow `ctx` naming
+ * only what that Plugin declared it may do.
  *
  * These declarations are types only. They mirror `core/contracts/isolate.ts`
  * member for member — `BOT_ISOLATE_CONTEXT_KEYS_V1` is the list this file's

package/src/build/paths.ts

@@ -1,28 +1,21 @@
 /**
- * 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.
+ * Where the SDK is on disk, so the Plugin build can resolve
+ * `@frockbot/applet-sdk/plugin` to its declarations.
  */
 
 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 three depths: `src/build/paths.ts` under Bun, the
- * bundled `dist/cli.mjs` under Node, and the build service's own bundle, which
- * is emitted into `dist/` for exactly this reason. A fixed `../../` is right
- * for one and silently wrong for the others — 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.
+ * The same module runs from two depths: `src/build/paths.ts` under Bun, and
+ * the build service's own bundle, which is emitted into `dist/` for exactly
+ * this reason. A fixed `../../` is right for one and silently wrong for the
+ * other — it would resolve the Plugin declarations to a file that does not
+ * exist and every Plugin import would fail to type-check with no explanation.
  */
 function findSdkRoot(): string {
   let directory = dirname(fileURLToPath(import.meta.url));
@@ -40,63 +33,12 @@ function findSdkRoot(): string {
     directory = parent;
   }
   throw new Error(
-    "the Applets SDK cannot find its own package root; reinstall @frockbot/applet-sdk",
+    "the Plugin 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",
-);
-
 /** The Plugin declarations (`@frockbot/applet-sdk/plugin`), types only. */
 export const SDK_PLUGIN_TYPES = join(SDK_ROOT, "plugin/index.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; the check stage reports the import.
-  }
-  return paths;
-}

package/src/build/plugin.ts

@@ -27,15 +27,54 @@ import { build as esbuild } from "esbuild";
 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";
 
+export interface PluginDiagnostic {
+  /** Path relative to the Plugin's directory. */
+  file: string;
+  line: number;
+  column: number;
+  message: string;
+  severity: "error" | "warning";
+}
+
 /** The Plugin's `plugin.json`, as far as the build reads it. */
 export interface PluginBuildDescriptorV1 {
   id: string;
@@ -69,11 +108,10 @@ export type PluginBuildOutcome =
   | {
       status: "failed";
       stage: PluginBuildStage;
-      diagnostics: AppletDiagnostic[];
+      diagnostics: PluginDiagnostic[];
     };
 
 const PLUGIN_ID = /^[a-z][a-z0-9-]{0,63}$/;
-const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
 const MAX_TOOLS = 64;
 
 const COMPILER_OPTIONS: ts.CompilerOptions = {
@@ -91,7 +129,7 @@ const COMPILER_OPTIONS: ts.CompilerOptions = {
   types: [],
 };
 
-function thrown(error: unknown, file = "plugin.json"): AppletDiagnostic[] {
+function thrown(error: unknown, file = "plugin.json"): PluginDiagnostic[] {
   return [
     {
       file,
@@ -153,7 +191,7 @@ async function pluginSources(directory: string): Promise<string[]> {
 /** Type-check the Plugin against the SDK's Plugin declarations. */
 export async function typeCheckPlugin(
   directory: string,
-): Promise<AppletDiagnostic[]> {
+): Promise<PluginDiagnostic[]> {
   const root = resolve(directory);
   const files = await pluginSources(root);
   if (!files.some((file) => relative(root, file) === "plugin.ts")) {
@@ -347,17 +385,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 +399,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 +409,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 +426,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(),
-  };
-}

package/src/lint/index.ts

@@ -1,148 +0,0 @@
-/**
- * `@frockbot/applet-sdk/lint` — the flat config, the rules, and the one call
- * the check stage makes.
- *
- * A diagnostic is the SDK's whole answer to "what did I do wrong": the CLI
- * prints `path:line:col message` and nothing else, so what a Bot must remember
- * is the message, not a manual.
- */
-
-import { readdir, readFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
-
-import { ESLint, type Linter, type Rule } from "eslint";
-import tseslint from "typescript-eslint";
-
-import { anchoredToToken, appletRules } from "./rules.js";
-
-export * from "./rules.js";
-
-export interface AppletDiagnostic {
-  /** Path relative to the Applet's directory. */
-  file: string;
-  line: number;
-  column: number;
-  message: string;
-  severity: "error" | "warning";
-}
-
-/** The one line the CLI prints per diagnostic. */
-export function formatDiagnostic(diagnostic: AppletDiagnostic): string {
-  return `${diagnostic.file}:${diagnostic.line}:${diagnostic.column} ${diagnostic.message}`;
-}
-
-export const appletPlugin = {
-  rules: appletRules as unknown as Record<string, Rule.RuleModule>,
-};
-
-/** The flat config an Applet is linted with. */
-export function appletLintConfig(): Linter.Config[] {
-  return [
-    {
-      files: ["**/*.ts", "**/*.tsx"],
-      languageOptions: {
-        parser: tseslint.parser as unknown as Linter.Parser,
-        parserOptions: {
-          ecmaVersion: 2023,
-          sourceType: "module",
-          ecmaFeatures: { jsx: true },
-        },
-      },
-      plugins: { applet: appletPlugin },
-      rules: {
-        "applet/no-raw-colors": "error",
-        "applet/no-network": "error",
-        "applet/allowed-imports": "error",
-        "applet/tables-via-table": "error",
-        "applet/tools-via-this-tool": "error",
-      },
-    },
-  ];
-}
-
-const CSS_COLOR =
-  /#[0-9a-fA-F]{3,8}\b|\brgba?\s*\([^)]*\)|\bhsla?\s*\([^)]*\)|\bcolor-mix\s*\(/g;
-
-/**
- * ESLint does not see `.css`, and a stylesheet is the easiest place to smuggle
- * a colour past the theme, so the same rule is applied here by hand.
- */
-export function lintCssText(text: string, file: string): AppletDiagnostic[] {
-  const diagnostics: AppletDiagnostic[] = [];
-  const lines = text.split("\n");
-  lines.forEach((line, index) => {
-    if (line.trimStart().startsWith("/*")) return;
-    for (const match of line.matchAll(CSS_COLOR)) {
-      // Judge the declaration the literal sits in, the same unit the TSX rule
-      // judges: a literal is fine where its own value names a theme token.
-      const start = line.lastIndexOf(";", match.index) + 1;
-      const end = line.indexOf(";", match.index);
-      const declaration = line.slice(start, end === -1 ? undefined : end);
-      if (anchoredToToken(declaration)) continue;
-      diagnostics.push({
-        file,
-        line: index + 1,
-        column: match.index + 1,
-        message:
-          `"${match[0]}" is a raw colour; use a --frockbot-* theme token ` +
-          "(or a var(--frockbot-…, fallback)).",
-        severity: "error",
-      });
-    }
-  });
-  return diagnostics;
-}
-
-async function sourceFiles(
-  directory: string,
-  extensions: 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 (extensions.some((extension) => entry.name.endsWith(extension))) {
-        found.push(path);
-      }
-    }
-  };
-  await walk(directory);
-  return found;
-}
-
-/** Lint one Applet directory. Returns diagnostics; never throws on a finding. */
-export async function lintApplet(
-  directory: string,
-): Promise<AppletDiagnostic[]> {
-  const root = resolve(directory);
-  const eslint = new ESLint({
-    cwd: root,
-    overrideConfigFile: true,
-    overrideConfig: appletLintConfig(),
-    errorOnUnmatchedPattern: false,
-  });
-  const results = await eslint.lintFiles(
-    await sourceFiles(root, [".ts", ".tsx"]),
-  );
-  const diagnostics: AppletDiagnostic[] = [];
-  for (const result of results) {
-    for (const message of result.messages) {
-      diagnostics.push({
-        file: relative(root, result.filePath),
-        line: message.line ?? 1,
-        column: message.column ?? 1,
-        message: `${message.message}${message.ruleId ? ` (${message.ruleId})` : ""}`,
-        severity: message.severity === 2 ? "error" : "warning",
-      });
-    }
-  }
-  for (const path of await sourceFiles(root, [".css"])) {
-    diagnostics.push(
-      ...lintCssText(await readFile(path, "utf8"), relative(root, path)),
-    );
-  }
-  return diagnostics;
-}

package/src/lint/rules.ts

@@ -1,394 +0,0 @@
-/**
- * The five rules that keep an Applet inside the SDK.
- *
- * Each one exists because of a way an Applet can look right and be wrong: a
- * hard-coded colour that ignores the user's theme, a network call the loader
- * would block anyway, an import that will not exist at build time, and state
- * or tools declared in a shape the server cannot see. This set grows from
- * observed failures — add a rule and a test here, never a paragraph in a
- * prompt.
- */
-
-/** A syntax node, walked structurally so no parser type leaks into the rules. */
-export interface AstNode {
-  type: string;
-  [field: string]: unknown;
-}
-
-export interface RuleContext {
-  report(descriptor: { node: AstNode; message: string }): void;
-}
-
-export interface AppletRule {
-  meta: {
-    type: "problem" | "suggestion";
-    docs: { description: string };
-    schema: [];
-    messages?: Record<string, string>;
-  };
-  create(context: RuleContext): Record<string, (node: AstNode) => void>;
-}
-
-function child(node: AstNode | undefined, field: string): AstNode | undefined {
-  const value = node?.[field];
-  return value && typeof value === "object" ? (value as AstNode) : undefined;
-}
-
-function name(node: AstNode | undefined): string | undefined {
-  if (!node) return undefined;
-  if (node.type === "Identifier" && typeof node.name === "string")
-    return node.name;
-  if (node.type === "Literal" && typeof node.value === "string")
-    return node.value;
-  return undefined;
-}
-
-function list(node: AstNode | undefined, field: string): AstNode[] {
-  const value = node?.[field];
-  return Array.isArray(value) ? (value as AstNode[]) : [];
-}
-
-// ---------------------------------------------------------------------------
-// no-raw-colors
-// ---------------------------------------------------------------------------
-
-const FUNCTIONAL_COLOR =
-  /#[0-9a-fA-F]{3,8}\b|\brgba?\s*\(|\bhsla?\s*\(|\bcolor-mix\s*\(/;
-const NAMED_COLORS = new Set([
-  "aqua",
-  "black",
-  "blue",
-  "brown",
-  "cyan",
-  "fuchsia",
-  "gold",
-  "gray",
-  "green",
-  "grey",
-  "indigo",
-  "lime",
-  "magenta",
-  "maroon",
-  "navy",
-  "olive",
-  "orange",
-  "pink",
-  "purple",
-  "red",
-  "silver",
-  "teal",
-  "violet",
-  "white",
-  "yellow",
-]);
-const COLOR_PROPERTIES = new Set([
-  "color",
-  "background",
-  "backgroundColor",
-  "borderColor",
-  "borderTopColor",
-  "borderRightColor",
-  "borderBottomColor",
-  "borderLeftColor",
-  "outlineColor",
-  "fill",
-  "stroke",
-  "caretColor",
-  "accentColor",
-  "textDecorationColor",
-  "boxShadow",
-  "textShadow",
-]);
-
-/**
- * A colour literal is fine only where the same value is anchored to a theme
- * token: as a `var(--frockbot-x, #fallback)` fallback, or as an ingredient of a
- * `color-mix()` over one. Anything else is a colour the User's theme cannot
- * move.
- */
-export function anchoredToToken(text: string): boolean {
-  return /var\(\s*--frockbot-[a-z-]+/.test(text);
-}
-
-export const noRawColors: AppletRule = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "Colours come from the nine --frockbot-* theme tokens, never from a literal",
-    },
-    schema: [],
-  },
-  create(context) {
-    const flag = (node: AstNode, text: string) => {
-      if (anchoredToToken(text)) return;
-      if (!FUNCTIONAL_COLOR.test(text)) return;
-      context.report({
-        node,
-        message:
-          "Use a --frockbot-* theme token instead of a colour literal " +
-          "(the kit's components already do).",
-      });
-    };
-    return {
-      Literal(node) {
-        if (typeof node.value === "string") flag(node, node.value);
-      },
-      TemplateElement(node) {
-        const value = child(node, "value");
-        const raw = value?.raw;
-        if (typeof raw === "string") flag(node, raw);
-      },
-      Property(node) {
-        const key = name(child(node, "key"));
-        if (!key || !COLOR_PROPERTIES.has(key)) return;
-        const value = child(node, "value");
-        if (value?.type !== "Literal" || typeof value.value !== "string")
-          return;
-        const text = value.value.trim().toLowerCase();
-        if (anchoredToToken(text) || !NAMED_COLORS.has(text)) return;
-        context.report({
-          node: value,
-          message: `"${text}" is a raw colour; use a --frockbot-* theme token.`,
-        });
-      },
-    };
-  },
-};
-
-// ---------------------------------------------------------------------------
-// no-network
-// ---------------------------------------------------------------------------
-
-const FORBIDDEN_CONSTRUCTORS = new Set([
-  "XMLHttpRequest",
-  "WebSocket",
-  "EventSource",
-]);
-
-export const noNetwork: AppletRule = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "An Applet reaches the outside world through its tools, never directly",
-    },
-    schema: [],
-  },
-  create(context) {
-    const complain = (node: AstNode, what: string) =>
-      context.report({
-        node,
-        message:
-          `${what} is not available to an Applet: the loader runs it with no ` +
-          "outbound network. Add a tool on the server, or use the Applet socket.",
-      });
-    return {
-      CallExpression(node) {
-        const callee = child(node, "callee");
-        if (name(callee) === "fetch") {
-          complain(node, "fetch()");
-          return;
-        }
-        if (callee?.type !== "MemberExpression") return;
-        const property = name(child(callee, "property"));
-        const object = name(child(callee, "object"));
-        if (
-          property === "fetch" &&
-          (object === "window" || object === "globalThis")
-        ) {
-          complain(node, "fetch()");
-        }
-        if (property === "sendBeacon" && object === "navigator") {
-          complain(node, "navigator.sendBeacon()");
-        }
-      },
-      NewExpression(node) {
-        const callee = name(child(node, "callee"));
-        if (callee && FORBIDDEN_CONSTRUCTORS.has(callee))
-          complain(node, `new ${callee}`);
-      },
-    };
-  },
-};
-
-// ---------------------------------------------------------------------------
-// allowed-imports
-// ---------------------------------------------------------------------------
-
-function importAllowed(specifier: string): boolean {
-  if (specifier.startsWith(".")) return true;
-  if (specifier === "react" || specifier.startsWith("react/")) return true;
-  return (
-    specifier === "@frockbot/applet-sdk" ||
-    specifier.startsWith("@frockbot/applet-sdk/")
-  );
-}
-
-export const allowedImports: AppletRule = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "An Applet bundles from @frockbot/applet-sdk, react, and its own files only",
-    },
-    schema: [],
-  },
-  create(context) {
-    const check = (node: AstNode, source: AstNode | undefined) => {
-      const specifier = source?.type === "Literal" ? source.value : undefined;
-      if (typeof specifier !== "string" || importAllowed(specifier)) return;
-      context.report({
-        node,
-        message:
-          `"${specifier}" cannot be imported: an Applet may import ` +
-          "@frockbot/applet-sdk/*, react, and its own relative files.",
-      });
-    };
-    return {
-      ImportDeclaration: (node) => check(node, child(node, "source")),
-      ExportNamedDeclaration: (node) => check(node, child(node, "source")),
-      ExportAllDeclaration: (node) => check(node, child(node, "source")),
-      ImportExpression: (node) => check(node, child(node, "source")),
-      CallExpression(node) {
-        if (name(child(node, "callee")) !== "require") return;
-        check(node, list(node, "arguments")[0]);
-      },
-    };
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Class-shape rules
-// ---------------------------------------------------------------------------
-
-function isAppletClassBody(node: AstNode): boolean {
-  const parent = child(node, "parent");
-  return name(child(parent, "superClass")) === "Applet";
-}
-
-function declaredProperty(node: AstNode, field: string): AstNode | undefined {
-  for (const member of list(node, "body")) {
-    if (member.type !== "PropertyDefinition") continue;
-    if (name(child(member, "key")) === field) return member;
-  }
-  return undefined;
-}
-
-export const tablesViaTable: AppletRule = {
-  meta: {
-    type: "problem",
-    docs: {
-      description: "Tables are declared with table() so the SDK can derive DDL",
-    },
-    schema: [],
-  },
-  create(context) {
-    // `tables = tables` naming a `const tables = { … }` is the shape the
-    // template uses, so the rule follows one level of indirection. The lookup
-    // happens on `Program:exit` so the declaration may come after the class.
-    const objectsByName = new Map<string, AstNode>();
-    const classBodies: AstNode[] = [];
-    return {
-      VariableDeclarator(node) {
-        const identifier = name(child(node, "id"));
-        const init = child(node, "init");
-        if (identifier && init?.type === "ObjectExpression") {
-          objectsByName.set(identifier, init);
-        }
-      },
-      ClassBody(node) {
-        if (isAppletClassBody(node)) classBodies.push(node);
-      },
-      "Program:exit"() {
-        for (const body of classBodies) {
-          const property = declaredProperty(body, "tables");
-          if (!property) continue;
-          const declared = child(property, "value");
-          const value =
-            declared?.type === "Identifier"
-              ? objectsByName.get(name(declared) ?? "")
-              : declared;
-          if (value?.type !== "ObjectExpression") {
-            context.report({
-              node: property,
-              message:
-                "`tables` must be an object literal of table({ … }) declarations.",
-            });
-            continue;
-          }
-          for (const entry of list(value, "properties")) {
-            const declaration = child(entry, "value");
-            if (
-              declaration?.type === "CallExpression" &&
-              name(child(declaration, "callee")) === "table"
-            ) {
-              continue;
-            }
-            context.report({
-              node: entry,
-              message:
-                "Each table must be declared with table({ … }) from the SDK.",
-            });
-          }
-        }
-      },
-    };
-  },
-};
-
-export const toolsViaThisTool: AppletRule = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "Tools are declared with this.tool() so health() can report them",
-    },
-    schema: [],
-  },
-  create(context) {
-    return {
-      ClassBody(node) {
-        if (!isAppletClassBody(node)) return;
-        const property = declaredProperty(node, "tools");
-        if (!property) return;
-        const value = child(property, "value");
-        if (value?.type !== "ObjectExpression") {
-          context.report({
-            node: property,
-            message:
-              "`tools` must be an object literal of this.tool(…) declarations.",
-          });
-          return;
-        }
-        for (const entry of list(value, "properties")) {
-          const declaration = child(entry, "value");
-          const callee = child(declaration, "callee");
-          if (
-            declaration?.type === "CallExpression" &&
-            callee?.type === "MemberExpression" &&
-            child(callee, "object")?.type === "ThisExpression" &&
-            name(child(callee, "property")) === "tool"
-          ) {
-            continue;
-          }
-          context.report({
-            node: entry,
-            message:
-              "Each tool must be declared with this.tool({ … }, handler).",
-          });
-        }
-      },
-    };
-  },
-};
-
-export const appletRules = {
-  "no-raw-colors": noRawColors,
-  "no-network": noNetwork,
-  "allowed-imports": allowedImports,
-  "tables-via-table": tablesViaTable,
-  "tools-via-this-tool": toolsViaThisTool,
-} satisfies Record<string, AppletRule>;
-
-export type AppletRuleName = keyof typeof appletRules;

package/types/cloudflare-workers.d.ts

@@ -1,55 +0,0 @@
-/**
- * The only part of the Cloudflare programming model the SDK names.
- *
- * The ceiling is deliberate: an Applet is a Durable Object with alarms and
- * hibernating sockets, and no adapter hides that. What this file does is keep
- * the surface to the handful of members `server/` actually uses, so an Applet
- * author never types a binding name and the SDK type-checks without
- * `@cloudflare/workers-types` in scope. It lives outside `src/` so a
- * consumer that already has the real Workers types cannot see two declarations
- * of the same module.
- */
-
-declare module "cloudflare:workers" {
-  export interface AppletSqlCursor {
-    toArray(): Array<Record<string, unknown>>;
-  }
-
-  export interface AppletSqlStorageHandle {
-    exec(query: string, ...bindings: unknown[]): AppletSqlCursor;
-  }
-
-  export interface AppletDurableObjectStorage {
-    readonly sql: AppletSqlStorageHandle;
-    transactionSync<T>(closure: () => T): T;
-    deleteAll(): Promise<void>;
-  }
-
-  export interface AppletHibernatableWebSocket {
-    send(message: string): void;
-    close(code?: number, reason?: string): void;
-    serializeAttachment(value: unknown): void;
-    deserializeAttachment(): unknown;
-  }
-
-  export interface AppletDurableObjectState {
-    readonly id: { toString(): string; readonly name?: string };
-    readonly storage: AppletDurableObjectStorage;
-    acceptWebSocket(socket: AppletHibernatableWebSocket, tags?: string[]): void;
-    getWebSockets(tag?: string): AppletHibernatableWebSocket[];
-    blockConcurrencyWhile<T>(closure: () => Promise<T>): Promise<T>;
-  }
-
-  export class DurableObject<Env = unknown> {
-    constructor(ctx: AppletDurableObjectState, env: Env);
-    protected readonly ctx: AppletDurableObjectState;
-    protected readonly env: Env;
-  }
-}
-
-declare const WebSocketPair: {
-  new (): {
-    0: import("cloudflare:workers").AppletHibernatableWebSocket;
-    1: import("cloudflare:workers").AppletHibernatableWebSocket;
-  };
-};