@frockbot/applet-sdk 0.0.0 → 0.3.13

package/dist/cli.mjs

@@ -0,0 +1,1007 @@
+#!/usr/bin/env node
+
+// src/cli/bin.ts
+import { resolve as resolve3 } from "node:path";
+
+// src/lint/index.ts
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { ESLint } from "eslint";
+import tseslint from "typescript-eslint";
+
+// src/lint/rules.ts
+function child(node, field) {
+  const value = node?.[field];
+  return value && typeof value === "object" ? value : void 0;
+}
+function name(node) {
+  if (!node) return void 0;
+  if (node.type === "Identifier" && typeof node.name === "string")
+    return node.name;
+  if (node.type === "Literal" && typeof node.value === "string")
+    return node.value;
+  return void 0;
+}
+function list(node, field) {
+  const value = node?.[field];
+  return Array.isArray(value) ? value : [];
+}
+var FUNCTIONAL_COLOR = /#[0-9a-fA-F]{3,8}\b|\brgba?\s*\(|\bhsla?\s*\(|\bcolor-mix\s*\(/;
+var NAMED_COLORS = /* @__PURE__ */ 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"
+]);
+var COLOR_PROPERTIES = /* @__PURE__ */ new Set([
+  "color",
+  "background",
+  "backgroundColor",
+  "borderColor",
+  "borderTopColor",
+  "borderRightColor",
+  "borderBottomColor",
+  "borderLeftColor",
+  "outlineColor",
+  "fill",
+  "stroke",
+  "caretColor",
+  "accentColor",
+  "textDecorationColor",
+  "boxShadow",
+  "textShadow"
+]);
+function anchoredToToken(text) {
+  return /var\(\s*--frockbot-[a-z-]+/.test(text);
+}
+var noRawColors = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Colours come from the nine --frockbot-* theme tokens, never from a literal"
+    },
+    schema: []
+  },
+  create(context) {
+    const flag = (node, text) => {
+      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.`
+        });
+      }
+    };
+  }
+};
+var FORBIDDEN_CONSTRUCTORS = /* @__PURE__ */ new Set([
+  "XMLHttpRequest",
+  "WebSocket",
+  "EventSource"
+]);
+var noNetwork = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "An Applet reaches the outside world through its tools, never directly"
+    },
+    schema: []
+  },
+  create(context) {
+    const complain = (node, what) => 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}`);
+      }
+    };
+  }
+};
+function importAllowed(specifier) {
+  if (specifier.startsWith(".")) return true;
+  if (specifier === "react" || specifier.startsWith("react/")) return true;
+  return specifier === "@frockbot/applet-sdk" || specifier.startsWith("@frockbot/applet-sdk/");
+}
+var allowedImports = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "An Applet bundles from @frockbot/applet-sdk, react, and its own files only"
+    },
+    schema: []
+  },
+  create(context) {
+    const check = (node, source) => {
+      const specifier = source?.type === "Literal" ? source.value : void 0;
+      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]);
+      }
+    };
+  }
+};
+function isAppletClassBody(node) {
+  const parent = child(node, "parent");
+  return name(child(parent, "superClass")) === "Applet";
+}
+function declaredProperty(node, field) {
+  for (const member of list(node, "body")) {
+    if (member.type !== "PropertyDefinition") continue;
+    if (name(child(member, "key")) === field) return member;
+  }
+  return void 0;
+}
+var tablesViaTable = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Tables are declared with table() so the SDK can derive DDL"
+    },
+    schema: []
+  },
+  create(context) {
+    const objectsByName = /* @__PURE__ */ new Map();
+    const classBodies = [];
+    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({ \u2026 }) 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({ \u2026 }) from the SDK."
+            });
+          }
+        }
+      }
+    };
+  }
+};
+var toolsViaThisTool = {
+  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(\u2026) 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({ \u2026 }, handler)."
+          });
+        }
+      }
+    };
+  }
+};
+var appletRules = {
+  "no-raw-colors": noRawColors,
+  "no-network": noNetwork,
+  "allowed-imports": allowedImports,
+  "tables-via-table": tablesViaTable,
+  "tools-via-this-tool": toolsViaThisTool
+};
+
+// src/lint/index.ts
+function formatDiagnostic(diagnostic) {
+  return `${diagnostic.file}:${diagnostic.line}:${diagnostic.column} ${diagnostic.message}`;
+}
+var appletPlugin = {
+  rules: appletRules
+};
+function appletLintConfig() {
+  return [
+    {
+      files: ["**/*.ts", "**/*.tsx"],
+      languageOptions: {
+        parser: tseslint.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"
+      }
+    }
+  ];
+}
+var CSS_COLOR = /#[0-9a-fA-F]{3,8}\b|\brgba?\s*\([^)]*\)|\bhsla?\s*\([^)]*\)|\bcolor-mix\s*\(/g;
+function lintCssText(text, file) {
+  const diagnostics = [];
+  const lines = text.split("\n");
+  lines.forEach((line, index) => {
+    if (line.trimStart().startsWith("/*")) return;
+    for (const match of line.matchAll(CSS_COLOR)) {
+      const start = line.lastIndexOf(";", match.index) + 1;
+      const end = line.indexOf(";", match.index);
+      const declaration = line.slice(start, end === -1 ? void 0 : 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-\u2026, fallback)).`,
+        severity: "error"
+      });
+    }
+  });
+  return diagnostics;
+}
+async function sourceFiles(directory, extensions) {
+  const found = [];
+  const walk = async (current) => {
+    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;
+}
+async function lintApplet(directory) {
+  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 = [];
+  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;
+}
+
+// src/cli/build.ts
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join as join4 } from "node:path";
+import { build as esbuild } from "esbuild";
+
+// src/cli/manifest.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+
+// src/protocol/index.ts
+var APPLET_CONTRACT_VERSION = 1;
+var APPLET_FRAME_BYTE_LIMIT = 64 * 1024;
+
+// src/cli/manifest.ts
+function decodeDescriptor(input) {
+  if (!input || typeof input !== "object")
+    throw new Error("applet.json must be an object");
+  const value = input;
+  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 };
+}
+async function readDescriptor(directory) {
+  const path = join2(directory, "applet.json");
+  let text;
+  try {
+    text = await readFile2(path, "utf8");
+  } catch {
+    throw new Error(
+      `No applet.json in ${directory}; run \`applet new <name>\` first`
+    );
+  }
+  return decodeDescriptor(JSON.parse(text));
+}
+
+// src/cli/paths.ts
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join as join3 } from "node:path";
+import { fileURLToPath } from "node:url";
+var require2 = createRequire(import.meta.url);
+function findSdkRoot() {
+  let directory = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 6; depth += 1) {
+    try {
+      const manifest = JSON.parse(
+        readFileSync(join3(directory, "package.json"), "utf8")
+      );
+      if (manifest.name === "@frockbot/applet-sdk") return `${directory}/`;
+    } catch {
+    }
+    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"
+  );
+}
+var SDK_ROOT = findSdkRoot();
+var SDK_ENTRIES = {
+  "@frockbot/applet-sdk/server": join3(SDK_ROOT, "src/server/index.ts"),
+  "@frockbot/applet-sdk/client": join3(SDK_ROOT, "src/client/index.ts"),
+  "@frockbot/applet-sdk/kit": join3(SDK_ROOT, "src/kit/index.tsx"),
+  "@frockbot/applet-sdk/protocol": join3(SDK_ROOT, "src/protocol/index.ts")
+};
+var SDK_WORKERS_TYPES = join3(
+  SDK_ROOT,
+  "types/cloudflare-workers.d.ts"
+);
+function packageDirectory(specifier) {
+  return dirname(require2.resolve(`${specifier}/package.json`));
+}
+function bundlerNodePaths() {
+  const paths = /* @__PURE__ */ new Set([join3(SDK_ROOT, "node_modules")]);
+  for (const specifier of [
+    "react",
+    "react-dom",
+    "@tanstack/db",
+    "@tanstack/react-db"
+  ]) {
+    try {
+      paths.add(join3(packageDirectory(specifier), "..", ".."));
+    } catch {
+    }
+  }
+  return [...paths];
+}
+function typeCheckerPaths() {
+  const paths = {};
+  for (const [specifier, file] of Object.entries(SDK_ENTRIES))
+    paths[specifier] = [file];
+  try {
+    const types = packageDirectory("@types/react");
+    paths.react = [join3(types, "index.d.ts")];
+    paths["react/jsx-runtime"] = [join3(types, "jsx-runtime.d.ts")];
+    paths["react/*"] = [join3(types, "*")];
+  } catch {
+  }
+  return paths;
+}
+
+// src/cli/runtime.ts
+import { convertV4MiniflareOptions, Miniflare } from "miniflare";
+var APPLET_COMPATIBILITY_DATE = "2026-08-27";
+var 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 });
+  },
+};
+`;
+async function startAppletRuntime(options) {
+  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
+    ),
+    dispose: () => miniflare.dispose()
+  };
+}
+
+// src/cli/build.ts
+function sha256(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function alias() {
+  return { ...SDK_ENTRIES };
+}
+async function bundle(options) {
+  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, 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");
+}
+async function readDescription(serverCode, appletId) {
+  const runtime = await startAppletRuntime({
+    serverCode,
+    appletId,
+    token: randomUUID()
+  });
+  try {
+    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();
+  } finally {
+    await runtime.dispose();
+  }
+}
+async function buildApplet(directory) {
+  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 = {
+    contract: 1,
+    tools: description.tools,
+    hashes: { server: sha256(serverCode), ui: sha256(html) }
+  };
+  const dist = join4(directory, "dist");
+  await mkdir(dist, { recursive: true });
+  const serverPath = join4(dist, "server.js");
+  const uiPath = join4(dist, "ui.html");
+  const manifestPath = join4(dist, "manifest.json");
+  await writeFile(serverPath, serverCode, "utf8");
+  await writeFile(uiPath, html, "utf8");
+  await writeFile(
+    manifestPath,
+    `${JSON.stringify(manifest, null, 2)}
+`,
+    "utf8"
+  );
+  return { directory, serverPath, uiPath, manifestPath, manifest };
+}
+
+// src/cli/check.ts
+import { readdir as readdir2 } from "node:fs/promises";
+import { join as join5, relative as relative2, resolve as resolve2 } from "node:path";
+import ts from "typescript";
+var COMPILER_OPTIONS = {
+  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) {
+  const found = [];
+  const walk = async (current) => {
+    for (const entry of await readdir2(current, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name === "dist") continue;
+      if (entry.name.startsWith(".")) continue;
+      const path = join5(current, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (/\.(ts|tsx)$/.test(entry.name)) found.push(path);
+    }
+  };
+  await walk(directory);
+  return found;
+}
+async function typeCheckApplet(directory) {
+  const root = resolve2(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 === void 0) {
+      return {
+        file: "applet.json",
+        line: 1,
+        column: 1,
+        message,
+        severity: "error"
+      };
+    }
+    const position = diagnostic.file.getLineAndCharacterOfPosition(
+      diagnostic.start
+    );
+    return {
+      file: relative2(root, diagnostic.file.fileName),
+      line: position.line + 1,
+      column: position.character + 1,
+      message: `${message} (TS${diagnostic.code})`,
+      severity: diagnostic.category === ts.DiagnosticCategory.Error ? "error" : "warning"
+    };
+  });
+}
+async function checkApplet(directory) {
+  const root = resolve2(directory);
+  const diagnostics = [];
+  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
+  );
+}
+
+// src/cli/dev.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { readFile as readFile3 } from "node:fs/promises";
+import { join as join6 } from "node:path";
+var DEV_THEME_TOKENS = {
+  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, token, generationId) {
+  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}
+</body>`);
+}
+async function startAppletDev(options) {
+  const descriptor = await readDescriptor(options.directory);
+  const dist = join6(options.directory, "dist");
+  let serverCode;
+  let html;
+  try {
+    serverCode = await readFile3(join6(dist, "server.js"), "utf8");
+    html = await readFile3(join6(dist, "ui.html"), "utf8");
+  } catch {
+    throw new Error("No dist/ to serve; run `applet build` first");
+  }
+  const token = randomUUID2();
+  const runtime = await startAppletRuntime({
+    serverCode,
+    html: injectDevInit(html, token, "dev"),
+    appletId: descriptor.id,
+    token,
+    port: options.port ?? 0
+  });
+  return { ...runtime, token };
+}
+
+// src/cli/new.ts
+import { mkdir as mkdir2, readdir as readdir3, readFile as readFile4, stat, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join7 } from "node:path";
+var TEMPLATE_ROOT = join7(SDK_ROOT, "template");
+function appletIdFrom(name2) {
+  const id = name2.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(`"${name2}" does not yield a usable Applet id`);
+  }
+  return id;
+}
+function fill(text, id, displayName) {
+  return text.replaceAll("__APPLET_ID__", id).replaceAll("__APPLET_NAME__", displayName);
+}
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function newApplet(options) {
+  const id = appletIdFrom(options.name);
+  const directory = join7(options.parent, id);
+  if (await exists(directory)) {
+    throw new Error(`${directory} already exists`);
+  }
+  const files = [];
+  const copy = async (from, to) => {
+    await mkdir2(to, { recursive: true });
+    for (const entry of await readdir3(from, { withFileTypes: true })) {
+      const source = join7(from, entry.name);
+      const target = join7(to, entry.name);
+      if (entry.isDirectory()) {
+        await copy(source, target);
+        continue;
+      }
+      const text = await readFile4(source, "utf8");
+      await writeFile2(target, fill(text, id, options.name), "utf8");
+      files.push(entry.name);
+    }
+  };
+  await copy(TEMPLATE_ROOT, directory);
+  return { id, displayName: options.name, directory, files };
+}
+
+// src/cli/bin.ts
+var 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
+`;
+function parseArgs(argv) {
+  const positional = [];
+  const options = {};
+  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) {
+  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;
+}
+async function run(argv) {
+  const { command, positional, options } = parseArgs(argv);
+  const directory = resolve3(positional[0] ?? ".");
+  switch (command) {
+    case "new": {
+      const name2 = positional[0];
+      if (!name2) {
+        console.error("applet new needs a name");
+        return 2;
+      }
+      const created = await newApplet({
+        name: name2,
+        parent: resolve3(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 === void 0 ? 0 : Number(options.port);
+      if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        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 === void 0 || command === "help" ? 0 : 2;
+  }
+}
+
+// src/cli/main.ts
+try {
+  process.exitCode = await run(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}