@frockbot/applet-sdk 0.0.0 → 0.3.13

package/package.json

@@ -1,14 +1,60 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
+  "version": "0.3.13",
+  "private": false,
+  "type": "module",
+  "description": "Authoring SDK for FrockBot Applets: schema-first Durable Object server, TanStack DB client, component kit, linter, and the `applet` CLI.",
   "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",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "applet": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "src",
+    "types",
+    "template",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun scripts/build-cli.ts",
+    "prepublishOnly": "bun scripts/build-cli.ts",
+    "test": "bun test test spike",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@tanstack/db": "0.8.7",
+    "@tanstack/react-db": "0.3.7",
+    "esbuild": "0.28.2",
+    "eslint": "10.9.1",
+    "miniflare": "5.20260828.0-alpha",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "@types/node": "26.2.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "react": "19.2.8",
+    "react-dom": "19.2.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/applet-sdk"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/cli/bin.ts

@@ -0,0 +1,128 @@
+/**
+ * `applet` — the four commands a Bot runs on the Computer.
+ *
+ * `scripts/build-cli.ts` bundles `./main.ts` (which calls `run` below) into
+ * `dist/cli.mjs`, and that file is the package's `bin`: the Computer image has
+ * Node and no Bun, and these sources are TypeScript resolving siblings through
+ * `.js` specifiers, which plain Node cannot load.
+ *
+ *   applet new <name> [--dir <parent>]
+ *   applet check [dir]
+ *   applet build [dir]
+ *   applet dev   [dir] [--port <n>]
+ *
+ * Output is deliberately spare: diagnostics as `path:line:col message`, one
+ * per line, and a non-zero exit when any of them is an error. That is the whole
+ * contract a Bot has to remember about this CLI.
+ */
+
+import { resolve } from "node:path";
+
+import { formatDiagnostic } from "../lint/index.js";
+import { buildApplet } from "./build.js";
+import { checkApplet } from "./check.js";
+import { startAppletDev } from "./dev.js";
+import { newApplet } from "./new.js";
+
+const USAGE = `applet <command>
+
+  new <name> [--dir <parent>]   scaffold an Applet from the template
+  check [dir]                   type-check and lint
+  build [dir]                   write dist/{server.js,ui.html,manifest.json}
+  dev [dir] [--port <n>]        serve the built Applet locally
+`;
+
+interface Args {
+  command?: string;
+  positional: string[];
+  options: Record<string, string>;
+}
+
+export function parseArgs(argv: string[]): Args {
+  const positional: string[] = [];
+  const options: Record<string, string> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]!;
+    if (token.startsWith("--")) {
+      const [flag, inline] = token.slice(2).split("=", 2);
+      options[flag!] = inline ?? argv[++index] ?? "";
+      continue;
+    }
+    positional.push(token);
+  }
+  return { command: positional.shift(), positional, options };
+}
+
+function report(diagnostics: Awaited<ReturnType<typeof checkApplet>>): number {
+  for (const diagnostic of diagnostics)
+    console.error(formatDiagnostic(diagnostic));
+  const errors = diagnostics.filter(
+    (diagnostic) => diagnostic.severity === "error",
+  );
+  if (errors.length === 0) {
+    console.log("applet check: no problems found");
+    return 0;
+  }
+  console.error(`applet check: ${errors.length} error(s)`);
+  return 1;
+}
+
+export async function run(argv: string[]): Promise<number> {
+  const { command, positional, options } = parseArgs(argv);
+  const directory = resolve(positional[0] ?? ".");
+
+  switch (command) {
+    case "new": {
+      const name = positional[0];
+      if (!name) {
+        console.error("applet new needs a name");
+        return 2;
+      }
+      const created = await newApplet({
+        name,
+        parent: resolve(options.dir ?? "."),
+      });
+      console.log(`Created ${created.directory} (id ${created.id})`);
+      console.log("Next: applet check && applet build");
+      return 0;
+    }
+    case "check":
+      return report(await checkApplet(directory));
+    case "build": {
+      const result = await buildApplet(directory);
+      console.log(
+        `${result.serverPath} ${result.manifest.hashes.server.slice(0, 12)}`,
+      );
+      console.log(`${result.uiPath} ${result.manifest.hashes.ui.slice(0, 12)}`);
+      console.log(
+        `${result.manifestPath} ${result.manifest.tools.length} tool(s): ` +
+          result.manifest.tools.map((tool) => tool.name).join(", "),
+      );
+      return 0;
+    }
+    case "dev": {
+      const port = options.port === undefined ? 0 : Number(options.port);
+      if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        console.error("applet dev --port must be a port number");
+        return 2;
+      }
+      const server = await startAppletDev({ directory, port });
+      console.log(server.url.toString());
+      const stop = () => {
+        void server.dispose().then(() => process.exit(0));
+      };
+      process.on("SIGINT", stop);
+      process.on("SIGTERM", stop);
+      await new Promise(() => {});
+      return 0;
+    }
+    default:
+      console.log(USAGE);
+      return command === undefined || command === "help" ? 0 : 2;
+  }
+}
+
+// No `import.meta.main` guard: this module is the command table, and
+// `./main.ts` is the entry point the published `dist/cli.mjs` bundles. Two
+// entry points would run every command twice under a Node that implements
+// `import.meta.main`, which is exactly what happened before this comment.

package/src/cli/build.ts

@@ -0,0 +1,181 @@
+/**
+ * `applet build` — three immutable artifacts from two source files.
+ *
+ * `dist/server.js`  one ESM file whose only import is `cloudflare:workers`,
+ *                   exporting `Applet`, which is the name the kernel mounts.
+ * `dist/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.
+ * `dist/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.
+ */
+
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { build as esbuild } from "esbuild";
+
+import type { AppletDescriptionV1 } from "../server/applet.js";
+import { readDescriptor, type AppletBuildManifestV1 } from "./manifest.js";
+import { bundlerNodePaths, SDK_ENTRIES } from "./paths.js";
+import { startAppletRuntime } from "./runtime.js";
+
+export interface AppletBuildResult {
+  directory: string;
+  serverPath: string;
+  uiPath: string;
+  manifestPath: string;
+  manifest: AppletBuildManifestV1;
+}
+
+function sha256(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function alias(): Record<string, string> {
+  return { ...SDK_ENTRIES };
+}
+
+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: alias(),
+    nodePaths: bundlerNodePaths(),
+    conditions: ["import", "module", "browser", "default"],
+    define: { "process.env.NODE_ENV": '"production"' },
+    logLevel: "silent",
+  });
+  const file = result.outputFiles?.[0];
+  if (!file) throw new Error("The bundler produced no output");
+  return file.text;
+}
+
+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>`,
+    "<style>html,body{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. */
+export async function readDescription(
+  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();
+  }
+}
+
+export async function buildApplet(
+  directory: string,
+): Promise<AppletBuildResult> {
+  const descriptor = await readDescriptor(directory);
+
+  const serverCode = 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",
+  });
+  const html = page(descriptor.displayName, uiScript);
+
+  const description = await readDescription(serverCode, descriptor.id);
+  const manifest: AppletBuildManifestV1 = {
+    contract: 1,
+    tools: description.tools,
+    hashes: { server: sha256(serverCode), ui: sha256(html) },
+  };
+
+  const dist = join(directory, "dist");
+  await mkdir(dist, { recursive: true });
+  const serverPath = join(dist, "server.js");
+  const uiPath = join(dist, "ui.html");
+  const manifestPath = join(dist, "manifest.json");
+  await writeFile(serverPath, serverCode, "utf8");
+  await writeFile(uiPath, html, "utf8");
+  await writeFile(
+    manifestPath,
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf8",
+  );
+
+  return { directory, serverPath, uiPath, manifestPath, manifest };
+}

package/src/cli/check.ts

@@ -0,0 +1,134 @@
+/**
+ * `applet check` — 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",
+      },
+    ];
+  }
+  const program = ts.createProgram([...files, SDK_WORKERS_TYPES], {
+    ...COMPILER_OPTIONS,
+    baseUrl: root,
+    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 `applet check` 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/cli/dev.ts

@@ -0,0 +1,84 @@
+/**
+ * `applet dev` — the built Applet on a local port, ready to be opened and
+ * screenshotted from the Computer's browser. It opens nothing itself.
+ */
+
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { readDescriptor } from "./manifest.js";
+import { startAppletRuntime, type AppletRuntime } from "./runtime.js";
+
+/**
+ * In production the shell nests the Applet page and sends it `init`. There is
+ * no shell here, so the dev page sends itself the same message — the page-side
+ * contract is identical, which is the point of running it this way at all.
+ */
+const DEV_THEME_TOKENS: Record<string, string> = {
+  surface: "#ffffff",
+  "surface-raised": "#ffffff",
+  "surface-subtle": "#f3f4f6",
+  text: "#16181d",
+  "text-muted": "#5b616b",
+  border: "#d8dbe0",
+  "accent-surface": "#2f6feb",
+  "accent-text": "#ffffff",
+  "radius-card": "10px",
+};
+
+function injectDevInit(
+  html: string,
+  token: string,
+  generationId: string,
+): string {
+  const init = {
+    schemaVersion: 1,
+    type: "init",
+    themeTokens: DEV_THEME_TOKENS,
+    packageId: "applets",
+    botId: "dev",
+    slot: "frockbot.right-panel",
+    applet: { socketUrl: "", token, generationId },
+  };
+  const script =
+    `<script>(()=>{const m=${JSON.stringify(init)};` +
+    `m.applet.socketUrl=location.origin.replace(/^http/,"ws")+"/socket";` +
+    `window.postMessage(m,"*");})();</script>`;
+  return html.replace("</body>", `${script}\n</body>`);
+}
+
+export interface AppletDevServer extends AppletRuntime {
+  token: string;
+}
+
+export interface AppletDevOptions {
+  directory: string;
+  /** 0 picks a free port. */
+  port?: number;
+}
+
+/** Serve `dist/` from Miniflare. Build first; this does not bundle. */
+export async function startAppletDev(
+  options: AppletDevOptions,
+): Promise<AppletDevServer> {
+  const descriptor = await readDescriptor(options.directory);
+  const dist = join(options.directory, "dist");
+  let serverCode: string;
+  let html: string;
+  try {
+    serverCode = await readFile(join(dist, "server.js"), "utf8");
+    html = await readFile(join(dist, "ui.html"), "utf8");
+  } catch {
+    throw new Error("No dist/ to serve; run `applet build` first");
+  }
+  const token = randomUUID();
+  const runtime = await startAppletRuntime({
+    serverCode,
+    html: injectDevInit(html, token, "dev"),
+    appletId: descriptor.id,
+    token,
+    port: options.port ?? 0,
+  });
+  return { ...runtime, token };
+}

package/src/cli/main.ts

@@ -0,0 +1,17 @@
+/**
+ * The bundled CLI's entry point.
+ *
+ * `bin.ts` guards its own execution with `import.meta.main` so it can be
+ * imported by tests under Bun. `dist/cli.mjs` is only ever executed, and it
+ * runs under whatever Node the Computer image ships — where `import.meta.main`
+ * may not exist, and where an absent guard would mean a CLI that exits 0 and
+ * does nothing. So the bundle gets its own entry with no guard at all.
+ */
+import { run } from "./bin.js";
+
+try {
+  process.exitCode = await run(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/src/cli/manifest.ts

@@ -0,0 +1,58 @@
+/** `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 directory name `applet new` creates. */
+  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}; run \`applet new <name>\` first`,
+    );
+  }
+  return decodeDescriptor(JSON.parse(text));
+}