@frockbot/applet-sdk 0.7.245 → 0.7.247

package/module/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `@frockbot/applet-sdk/module`: what a Plugin's device module is written
+ * against (ADR 0037).
+ *
+ * A module is `modules/<id>.ts` in the Plugin's source. The desktop runs it in
+ * its own Deno process, which can read only the paths its descriptor's `read`
+ * names and reach only the addresses its `net` names. It may use Node's
+ * built-in modules (`node:fs`, `node:sqlite`, …), `fetch` and `WebSocket` like
+ * any other program, within those limits.
+ *
+ * A module exports its `calls`, one function for each call the descriptor
+ * declares, and may export `start`, which runs for as long as the app does and
+ * is where a module holds a connection and emits events.
+ */
+
+/** One event the module sends to the cloud, to fire the Plugin's triggers. */
+export interface ModuleEmitOptions {
+  /**
+   * The source's own id for this occurrence. A replay under the same key is
+   * the same event, so a reconnect never fires a Routine twice.
+   */
+  key: string;
+}
+
+/** What the host hands a module. */
+export interface ModuleContext {
+  /** Sends one event to the cloud. `event` must be one the descriptor names. */
+  emit(
+    event: string,
+    payload: unknown,
+    options: ModuleEmitOptions,
+  ): Promise<void>;
+  /** The last key the cloud acknowledged for `event`, to catch up from. */
+  lastKey(event: string): Promise<string | undefined>;
+  /** A line the Bot reads back with `plugin_module_reports`. */
+  log(level: "log" | "error", text: string): void;
+  /** A small key-value store on this device, for the module alone. */
+  store: {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+  };
+  /** Runs an AppleScript against an application the descriptor names. */
+  appleEvents: {
+    run(bundleId: string, script: string): Promise<string>;
+  };
+  /** Aborts when the host stops the module. */
+  signal: AbortSignal;
+}
+
+/** One call the Plugin's cloud code may make. Its answer must be JSON. */
+export type ModuleCall = (input: unknown, context: ModuleContext) => unknown;
+
+export type ModuleCalls = Record<string, ModuleCall>;
+
+/** Runs for as long as the app does; resolve or throw to stop. */
+export type ModuleStart = (context: ModuleContext) => Promise<void> | void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.245",
+  "version": "0.7.247",
   "private": false,
   "type": "module",
   "description": "Authoring SDK for FrockBot Plugins: the declarations a Plugin is written against, and the build pipeline the cloud build service runs.",
@@ -8,11 +8,13 @@
   "exports": {
     "./build/plugin": "./src/build/plugin.ts",
     "./plugin": "./plugin/index.d.ts",
+    "./module": "./module/index.d.ts",
     "./package.json": "./package.json"
   },
   "files": [
     "src",
     "plugin",
+    "module",
     "README.md"
   ],
   "scripts": {

package/src/build/paths.ts

@@ -42,3 +42,6 @@ export const SDK_ROOT = findSdkRoot();
 
 /** The Plugin declarations (`@frockbot/applet-sdk/plugin`), types only. */
 export const SDK_PLUGIN_TYPES = join(SDK_ROOT, "plugin/index.d.ts");
+
+/** The device module declarations (`@frockbot/applet-sdk/module`), types only. */
+export const SDK_MODULE_TYPES = join(SDK_ROOT, "module/index.d.ts");

package/src/build/plugin.ts

@@ -28,7 +28,7 @@ import { convertV4MiniflareOptions, Miniflare } from "miniflare";
 import ts from "typescript";
 
 import { stableModulePaths } from "./module-paths.js";
-import { SDK_PLUGIN_TYPES } from "./paths.js";
+import { SDK_MODULE_TYPES, SDK_PLUGIN_TYPES, SDK_ROOT } from "./paths.js";
 
 /** Pinned with the SDK: the runtime a Plugin build is checked against. */
 const PLUGIN_COMPATIBILITY_DATE = "2026-08-27";
@@ -78,6 +78,15 @@ export interface PluginDiagnostic {
 /** The Plugin's `plugin.json`, as far as the build reads it. */
 export interface PluginBuildDescriptorV1 {
   id: string;
+  /** The device modules it declares, by id (ADR 0037). */
+  modules: string[];
+}
+
+/** One built device module: its id, what it exports as calls, and its code. */
+export interface PluginBuiltModuleV1 {
+  id: string;
+  calls: string[];
+  code: string;
 }
 
 /** What the built module exports, read by running it. */
@@ -99,12 +108,19 @@ export interface PluginDescriptionV1 {
 
 export interface PluginBuildManifestV1 extends PluginDescriptionV1 {
   contract: 1;
+  /** Each device module, with the calls it exports and its hash. */
+  modules: { id: string; calls: string[]; hash: string }[];
   hashes: { module: string };
 }
 
 export type PluginBuildOutcome =
   | { status: "checked" }
-  | { status: "built"; manifest: PluginBuildManifestV1; module: string }
+  | {
+      status: "built";
+      manifest: PluginBuildManifestV1;
+      module: string;
+      modules: { id: string; code: string }[];
+    }
   | {
       status: "failed";
       stage: PluginBuildStage;
@@ -112,7 +128,9 @@ export type PluginBuildOutcome =
     };
 
 const PLUGIN_ID = /^[a-z][a-z0-9-]{0,63}$/;
+const MODULE_ID = /^[a-z][a-z0-9-]{0,31}$/;
 const MAX_TOOLS = 64;
+const MODULES_DIRECTORY = "modules";
 
 const COMPILER_OPTIONS: ts.CompilerOptions = {
   target: ts.ScriptTarget.ES2022,
@@ -129,6 +147,16 @@ const COMPILER_OPTIONS: ts.CompilerOptions = {
   types: [],
 };
 
+/**
+ * A device module runs in Deno on the desktop, not in a Worker: it gets Node's
+ * built-in modules as well as the web platform, and its own declarations.
+ */
+const MODULE_COMPILER_OPTIONS: ts.CompilerOptions = {
+  ...COMPILER_OPTIONS,
+  types: ["node"],
+  typeRoots: [join(SDK_ROOT, "node_modules/@types")],
+};
+
 function thrown(error: unknown, file = "plugin.json"): PluginDiagnostic[] {
   return [
     {
@@ -169,14 +197,30 @@ export async function readPluginDescriptor(
   if (typeof id !== "string" || !PLUGIN_ID.test(id)) {
     throw new Error('plugin.json "id" must match /^[a-z][a-z0-9-]{0,63}$/');
   }
-  return { id };
+  // Only the ids: the app decodes the rest of the declaration.
+  const declared = (parsed as { device?: { modules?: unknown } }).device
+    ?.modules;
+  const modules = (Array.isArray(declared) ? declared : []).map((module) => {
+    const moduleId = (module as { id?: unknown } | null)?.id;
+    if (typeof moduleId !== "string" || !MODULE_ID.test(moduleId)) {
+      throw new Error(
+        'plugin.json "device.modules" ids must match /^[a-z][a-z0-9-]{0,31}$/',
+      );
+    }
+    return moduleId;
+  });
+  return { id, modules };
 }
 
-async function pluginSources(directory: string): Promise<string[]> {
+async function pluginSources(
+  directory: string,
+  skip: readonly 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.startsWith(".")) continue;
+      if (current === directory && skip.includes(entry.name)) continue;
       const path = join(current, entry.name);
       if (entry.isDirectory()) await walk(path);
       else if (/\.ts$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
@@ -193,7 +237,8 @@ export async function typeCheckPlugin(
   directory: string,
 ): Promise<PluginDiagnostic[]> {
   const root = resolve(directory);
-  const files = await pluginSources(root);
+  // A device module runs in Deno, not in the Worker, and is checked as such.
+  const files = await pluginSources(root, [MODULES_DIRECTORY]);
   if (!files.some((file) => relative(root, file) === "plugin.ts")) {
     return [
       {
@@ -209,6 +254,13 @@ export async function typeCheckPlugin(
     ...COMPILER_OPTIONS,
     paths: { "@frockbot/applet-sdk/plugin": [SDK_PLUGIN_TYPES] },
   });
+  return programDiagnostics(program, root);
+}
+
+function programDiagnostics(
+  program: ts.Program,
+  root: string,
+): PluginDiagnostic[] {
   return ts
     .getPreEmitDiagnostics(program)
     .filter(
@@ -245,6 +297,126 @@ export async function typeCheckPlugin(
     });
 }
 
+/**
+ * Type-check the Plugin's device modules and read the calls each exports.
+ *
+ * One program over `modules/`, with Node's declarations and the module SDK's.
+ * The calls are read from the checker, so `calls` may be built however the
+ * module likes as long as its type names them.
+ */
+export async function typeCheckModules(
+  directory: string,
+  moduleIds: readonly string[],
+): Promise<
+  | { status: "ok"; calls: Map<string, string[]> }
+  | { status: "failed"; diagnostics: PluginDiagnostic[] }
+> {
+  const root = resolve(directory);
+  const modulesRoot = join(root, MODULES_DIRECTORY);
+  const entries = moduleIds.map((id) => join(modulesRoot, `${id}.ts`));
+  let files: string[] = [];
+  try {
+    files = await pluginSources(modulesRoot);
+  } catch {
+    // No modules directory: every declared entry is missing, said below.
+  }
+  const missing = entries.filter((entry) => !files.includes(entry));
+  if (missing.length > 0) {
+    return {
+      status: "failed",
+      diagnostics: missing.map((entry) => ({
+        file: relative(root, entry),
+        line: 1,
+        column: 1,
+        message: `plugin.json declares a device module whose source ${relative(root, entry)} does not exist`,
+        severity: "error" as const,
+      })),
+    };
+  }
+  const program = ts.createProgram(files, {
+    ...MODULE_COMPILER_OPTIONS,
+    paths: { "@frockbot/applet-sdk/module": [SDK_MODULE_TYPES] },
+  });
+  const diagnostics = programDiagnostics(program, root);
+  if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    return { status: "failed", diagnostics };
+  }
+  const checker = program.getTypeChecker();
+  const calls = new Map<string, string[]>();
+  const problems: PluginDiagnostic[] = [];
+  for (const [index, entry] of entries.entries()) {
+    const source = program.getSourceFile(entry);
+    const symbol = source && checker.getSymbolAtLocation(source);
+    const exported = symbol
+      ? checker
+          .getExportsOfModule(symbol)
+          .find((candidate) => candidate.name === "calls")
+      : undefined;
+    if (!source || !exported) {
+      problems.push({
+        file: relative(root, entry),
+        line: 1,
+        column: 1,
+        message: 'a device module must export "calls"',
+        severity: "error",
+      });
+      continue;
+    }
+    const type = checker.getTypeOfSymbolAtLocation(exported, source);
+    calls.set(
+      moduleIds[index]!,
+      checker.getPropertiesOfType(type).map((property) => property.name),
+    );
+  }
+  return problems.length > 0
+    ? { status: "failed", diagnostics: problems }
+    : { status: "ok", calls };
+}
+
+/**
+ * One ES module per device module, for Deno. Node's built-ins stay imports,
+ * resolved by the runtime; everything else is inlined, so the module needs
+ * nothing fetched at start.
+ */
+export async function bundleModule(
+  directory: string,
+  moduleId: string,
+): Promise<string> {
+  const result = await esbuild({
+    entryPoints: [join(directory, MODULES_DIRECTORY, `${moduleId}.ts`)],
+    bundle: true,
+    write: false,
+    format: "esm",
+    platform: "node",
+    target: "es2022",
+    minify: false,
+    legalComments: "none",
+    external: ["node:*"],
+    plugins: [
+      {
+        name: "module-sdk-is-types-only",
+        setup(build) {
+          build.onResolve(
+            { filter: /^@frockbot\/applet-sdk\/module$/ },
+            () => ({
+              errors: [
+                {
+                  text: '"@frockbot/applet-sdk/module" is types only; import it with `import type`.',
+                },
+              ],
+            }),
+          );
+        },
+      },
+    ],
+    metafile: true,
+    logLevel: "silent",
+  });
+  const file = result.outputFiles?.[0];
+  if (!file) throw new Error("The bundler produced no output");
+  return stableModulePaths(file.text, result.metafile, directory);
+}
+
 /**
  * One ESM module, every import inlined. `@frockbot/applet-sdk/plugin` is
  * types only, so a value import of it is the one specifier that can never
@@ -498,6 +670,18 @@ export async function runPluginBuildV1(
   if (types.some((diagnostic) => diagnostic.severity === "error")) {
     return { status: "failed", stage: "typecheck", diagnostics: types };
   }
+  let moduleCalls = new Map<string, string[]>();
+  if (descriptor.modules.length > 0) {
+    const checked = await typeCheckModules(directory, descriptor.modules);
+    if (checked.status === "failed") {
+      return {
+        status: "failed",
+        stage: "typecheck",
+        diagnostics: checked.diagnostics,
+      };
+    }
+    moduleCalls = checked.calls;
+  }
   if (options.mode === "check") return { status: "checked" };
 
   let moduleCode: string;
@@ -511,6 +695,19 @@ export async function runPluginBuildV1(
     };
   }
 
+  const modules: { id: string; code: string }[] = [];
+  for (const id of descriptor.modules) {
+    try {
+      modules.push({ id, code: await bundleModule(directory, id) });
+    } catch (error) {
+      return {
+        status: "failed",
+        stage: "bundle",
+        diagnostics: thrown(error, `${MODULES_DIRECTORY}/${id}.ts`),
+      };
+    }
+  }
+
   let description: PluginDescriptionV1;
   try {
     description = await describePlugin(moduleCode);
@@ -526,8 +723,14 @@ export async function runPluginBuildV1(
     manifest: {
       contract: 1,
       ...description,
+      modules: modules.map((module) => ({
+        id: module.id,
+        calls: moduleCalls.get(module.id) ?? [],
+        hash: sha256(module.code),
+      })),
       hashes: { module: sha256(moduleCode) },
     },
     module: moduleCode,
+    modules,
   };
 }