@frockbot/applet-sdk 0.0.0 → 0.3.13

package/src/server/store.ts

@@ -0,0 +1,398 @@
+/**
+ * The SQLite side of an Applet: DDL, typed rows, and the change log.
+ *
+ * Everything here is synchronous against a `SqlStorage`-shaped handle, so the
+ * caller can wrap a whole client transaction in `ctx.storage.transactionSync`
+ * and so the whole module is testable against any SQLite driver.
+ */
+
+import {
+  AppletValidationError,
+  addColumnStatement,
+  createTableStatement,
+  decodeValue,
+  encodeValue,
+  quoteIdentifier,
+  schemaFingerprint,
+  type SqlValue,
+  type TableDefinition,
+  type TablesShape,
+} from "../schema/index.js";
+import type { AppletChangeV1, AppletMutationV1 } from "../protocol/index.js";
+
+/** The subset of Cloudflare's `SqlStorage` the SDK uses. */
+export interface AppletSqlStorage {
+  exec(
+    query: string,
+    ...bindings: unknown[]
+  ): { toArray(): Array<Record<string, unknown>> };
+}
+
+const META_TABLE = "_applet_meta";
+const CHANGE_TABLE = "_applet_changes";
+/** Retained change-log length; a client further behind gets a full snapshot. */
+export const CHANGE_LOG_LIMIT = 2_000;
+
+export interface SchemaState {
+  revision: number;
+  /** True when this mount changed the declared shape. */
+  changed: boolean;
+  previousRevision: number;
+}
+
+export class AppletStore {
+  private readonly sql: AppletSqlStorage;
+  readonly tables: TablesShape;
+  private cursor = 0;
+
+  constructor(sql: AppletSqlStorage, tables: TablesShape) {
+    this.sql = sql;
+    this.tables = tables;
+  }
+
+  /**
+   * Idempotent DDL. Creates the SDK's own tables and every declared table,
+   * adds columns declared since the last mount, and reports whether the shape
+   * moved so the caller can run `migrate`.
+   */
+  ensureSchema(): SchemaState {
+    this.sql.exec(
+      `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(META_TABLE)} ("key" TEXT PRIMARY KEY NOT NULL, "value" TEXT NOT NULL)`,
+    );
+    this.sql.exec(
+      `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(CHANGE_TABLE)} (` +
+        `"seq" INTEGER PRIMARY KEY AUTOINCREMENT, "txnId" TEXT, "tbl" TEXT NOT NULL, ` +
+        `"op" TEXT NOT NULL, "rowKey" TEXT NOT NULL, "row" TEXT, "at" TEXT NOT NULL)`,
+    );
+
+    for (const [name, definition] of Object.entries(this.tables)) {
+      this.sql.exec(createTableStatement(name, definition));
+      const existing = new Set(
+        this.sql
+          .exec(`PRAGMA table_info(${quoteIdentifier(name)})`)
+          .toArray()
+          .map((column) => String(column.name)),
+      );
+      for (const [column, spec] of Object.entries(definition.columns)) {
+        if (existing.has(column)) continue;
+        this.sql.exec(addColumnStatement(name, column, spec));
+      }
+    }
+
+    this.cursor = Number(
+      this.sql
+        .exec(`SELECT MAX("seq") AS seq FROM ${quoteIdentifier(CHANGE_TABLE)}`)
+        .toArray()[0]?.seq ?? 0,
+    );
+
+    const fingerprint = schemaFingerprint(this.tables);
+    const storedFingerprint = this.readMeta("schema:fingerprint");
+    const previousRevision = Number(this.readMeta("schema:revision") ?? 0);
+    if (storedFingerprint === fingerprint) {
+      return { revision: previousRevision, changed: false, previousRevision };
+    }
+    const revision = previousRevision + 1;
+    this.writeMeta("schema:fingerprint", fingerprint);
+    this.writeMeta("schema:revision", String(revision));
+    return { revision, changed: true, previousRevision };
+  }
+
+  private readMeta(key: string): string | undefined {
+    const rows = this.sql
+      .exec(
+        `SELECT "value" FROM ${quoteIdentifier(META_TABLE)} WHERE "key" = ?`,
+        key,
+      )
+      .toArray();
+    return rows.length === 0 ? undefined : String(rows[0]!.value);
+  }
+
+  private writeMeta(key: string, value: string): void {
+    this.sql.exec(
+      `INSERT INTO ${quoteIdentifier(META_TABLE)} ("key", "value") VALUES (?, ?) ` +
+        `ON CONFLICT("key") DO UPDATE SET "value" = excluded."value"`,
+      key,
+      value,
+    );
+  }
+
+  get lastChangeId(): number {
+    return this.cursor;
+  }
+
+  /** Fail closed on a table the Applet did not declare. */
+  private definition(table: string): TableDefinition {
+    const definition = this.tables[table];
+    if (!definition) {
+      throw new AppletValidationError(`Unknown table "${table}"`);
+    }
+    return definition;
+  }
+
+  private decodeRow(
+    definition: TableDefinition,
+    raw: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const row: Record<string, unknown> = {};
+    for (const [column, spec] of Object.entries(definition.columns)) {
+      row[column] = decodeValue(spec.definition, raw[column]);
+    }
+    return row;
+  }
+
+  private encodeInsert(
+    table: string,
+    definition: TableDefinition,
+    values: Record<string, unknown>,
+    suppliedKey?: string,
+  ): { key: string; columns: string[]; bindings: SqlValue[] } {
+    for (const column of Object.keys(values)) {
+      if (!Object.hasOwn(definition.columns, column)) {
+        throw new AppletValidationError(`Unknown column "${table}.${column}"`);
+      }
+    }
+    const columns: string[] = [];
+    const bindings: SqlValue[] = [];
+    let key = suppliedKey;
+    for (const [column, spec] of Object.entries(definition.columns)) {
+      const meta = spec.definition;
+      let value = values[column];
+      if (column === definition.primaryKey) {
+        value =
+          (value as string | undefined) ?? suppliedKey ?? crypto.randomUUID();
+        key = value as string;
+      } else if (value === undefined) {
+        if (meta.hasDefault) value = meta.defaultValue;
+        else if (meta.optional) value = null;
+        else {
+          throw new AppletValidationError(
+            `Column "${table}.${column}" is required`,
+          );
+        }
+      }
+      columns.push(column);
+      bindings.push(encodeValue(`${table}.${column}`, meta, value));
+    }
+    return { key: key!, columns, bindings };
+  }
+
+  insert(
+    table: string,
+    values: Record<string, unknown>,
+    txnId?: string,
+  ): AppletChangeV1 {
+    const definition = this.definition(table);
+    const { key, columns, bindings } = this.encodeInsert(
+      table,
+      definition,
+      values,
+    );
+    this.sql.exec(
+      `INSERT INTO ${quoteIdentifier(table)} (${columns.map(quoteIdentifier).join(", ")}) ` +
+        `VALUES (${columns.map(() => "?").join(", ")})`,
+      ...bindings,
+    );
+    const row = this.read(table, key);
+    if (!row)
+      throw new AppletValidationError(`Insert into "${table}" did not persist`);
+    return this.log({ table, op: "insert", key, row }, txnId);
+  }
+
+  update(
+    table: string,
+    key: string,
+    patch: Record<string, unknown>,
+    txnId?: string,
+  ): AppletChangeV1 | undefined {
+    const definition = this.definition(table);
+    const assignments: string[] = [];
+    const bindings: SqlValue[] = [];
+    for (const [column, value] of Object.entries(patch)) {
+      if (!Object.hasOwn(definition.columns, column)) {
+        throw new AppletValidationError(`Unknown column "${table}.${column}"`);
+      }
+      if (column === definition.primaryKey) {
+        throw new AppletValidationError(
+          `Column "${table}.${column}" is the key`,
+        );
+      }
+      assignments.push(`${quoteIdentifier(column)} = ?`);
+      bindings.push(
+        encodeValue(
+          `${table}.${column}`,
+          definition.columns[column]!.definition,
+          value,
+        ),
+      );
+    }
+    if (assignments.length === 0) return undefined;
+    if (!this.read(table, key)) return undefined;
+    this.sql.exec(
+      `UPDATE ${quoteIdentifier(table)} SET ${assignments.join(", ")} ` +
+        `WHERE ${quoteIdentifier(definition.primaryKey)} = ?`,
+      ...bindings,
+      key,
+    );
+    const row = this.read(table, key);
+    if (!row) return undefined;
+    return this.log({ table, op: "update", key, row }, txnId);
+  }
+
+  delete(
+    table: string,
+    key: string,
+    txnId?: string,
+  ): AppletChangeV1 | undefined {
+    const definition = this.definition(table);
+    if (!this.read(table, key)) return undefined;
+    this.sql.exec(
+      `DELETE FROM ${quoteIdentifier(table)} WHERE ${quoteIdentifier(definition.primaryKey)} = ?`,
+      key,
+    );
+    return this.log({ table, op: "delete", key }, txnId);
+  }
+
+  read(table: string, key: string): Record<string, unknown> | undefined {
+    const definition = this.definition(table);
+    const rows = this.sql
+      .exec(
+        `SELECT * FROM ${quoteIdentifier(table)} WHERE ${quoteIdentifier(definition.primaryKey)} = ? LIMIT 1`,
+        key,
+      )
+      .toArray();
+    return rows.length === 0 ? undefined : this.decodeRow(definition, rows[0]!);
+  }
+
+  /** Every row, or the rows whose declared columns all equal `filter`. */
+  select(
+    table: string,
+    filter?: Record<string, unknown>,
+  ): Array<Record<string, unknown>> {
+    const definition = this.definition(table);
+    const clauses: string[] = [];
+    const bindings: SqlValue[] = [];
+    for (const [column, value] of Object.entries(filter ?? {})) {
+      if (!Object.hasOwn(definition.columns, column)) {
+        throw new AppletValidationError(`Unknown column "${table}.${column}"`);
+      }
+      const encoded = encodeValue(
+        `${table}.${column}`,
+        definition.columns[column]!.definition,
+        value,
+      );
+      if (encoded === null) {
+        clauses.push(`${quoteIdentifier(column)} IS NULL`);
+      } else {
+        clauses.push(`${quoteIdentifier(column)} = ?`);
+        bindings.push(encoded);
+      }
+    }
+    const where = clauses.length === 0 ? "" : ` WHERE ${clauses.join(" AND ")}`;
+    return this.sql
+      .exec(`SELECT * FROM ${quoteIdentifier(table)}${where}`, ...bindings)
+      .toArray()
+      .map((row) => this.decodeRow(definition, row));
+  }
+
+  /** Apply one client transaction. The caller wraps this in a SQL transaction. */
+  applyMutations(
+    mutations: AppletMutationV1[],
+    txnId?: string,
+  ): AppletChangeV1[] {
+    return mutations.map((mutation) => {
+      const change =
+        mutation.op === "insert"
+          ? this.insert(
+              mutation.table,
+              mutation.key === undefined
+                ? (mutation.value ?? {})
+                : {
+                    ...(mutation.value ?? {}),
+                    [this.definition(mutation.table).primaryKey]: mutation.key,
+                  },
+              txnId,
+            )
+          : mutation.op === "update"
+            ? this.update(
+                mutation.table,
+                mutation.key!,
+                mutation.value ?? {},
+                txnId,
+              )
+            : this.delete(mutation.table, mutation.key!, txnId);
+      if (!change) {
+        throw new AppletValidationError(
+          `Row "${mutation.key}" is not in "${mutation.table}"`,
+        );
+      }
+      return change;
+    });
+  }
+
+  private log(change: AppletChangeV1, txnId?: string): AppletChangeV1 {
+    this.sql.exec(
+      `INSERT INTO ${quoteIdentifier(CHANGE_TABLE)} ("txnId", "tbl", "op", "rowKey", "row", "at") VALUES (?, ?, ?, ?, ?, ?)`,
+      txnId ?? null,
+      change.table,
+      change.op,
+      change.key,
+      change.row === undefined ? null : JSON.stringify(change.row),
+      new Date().toISOString(),
+    );
+    this.cursor = Number(
+      this.sql
+        .exec(`SELECT MAX("seq") AS seq FROM ${quoteIdentifier(CHANGE_TABLE)}`)
+        .toArray()[0]!.seq,
+    );
+    this.trim();
+    return change;
+  }
+
+  private trim(): void {
+    if (this.cursor <= CHANGE_LOG_LIMIT) return;
+    this.sql.exec(
+      `DELETE FROM ${quoteIdentifier(CHANGE_TABLE)} WHERE "seq" <= ?`,
+      this.cursor - CHANGE_LOG_LIMIT,
+    );
+  }
+
+  /** The whole state, table by table, in declaration order. */
+  snapshot(): Record<string, Array<Record<string, unknown>>> {
+    const tables: Record<string, Array<Record<string, unknown>>> = {};
+    for (const name of Object.keys(this.tables))
+      tables[name] = this.select(name);
+    return tables;
+  }
+
+  /**
+   * Changes after `cursor`, or `undefined` when the log no longer reaches back
+   * that far and the client must take a full snapshot instead.
+   */
+  changesSince(cursor: number): AppletChangeV1[] | undefined {
+    if (cursor > this.cursor) return undefined;
+    if (cursor === this.cursor) return [];
+    const oldest = Number(
+      this.sql
+        .exec(`SELECT MIN("seq") AS seq FROM ${quoteIdentifier(CHANGE_TABLE)}`)
+        .toArray()[0]?.seq ?? 0,
+    );
+    if (oldest === 0 || oldest > cursor + 1) return undefined;
+    return this.sql
+      .exec(
+        `SELECT "tbl", "op", "rowKey", "row" FROM ${quoteIdentifier(CHANGE_TABLE)} WHERE "seq" > ? ORDER BY "seq" ASC`,
+        cursor,
+      )
+      .toArray()
+      .map((entry) => {
+        const change: AppletChangeV1 = {
+          table: String(entry.tbl),
+          op: String(entry.op) as AppletChangeV1["op"],
+          key: String(entry.rowKey),
+        };
+        if (entry.row !== null && entry.row !== undefined) {
+          change.row = JSON.parse(String(entry.row)) as Record<string, unknown>;
+        }
+        return change;
+      });
+  }
+}

package/template/README.md

@@ -0,0 +1,37 @@
+# __APPLET_NAME__
+
+A FrockBot Applet. Two files are yours:
+
+| File        | What it owns                                                               |
+| ----------- | -------------------------------------------------------------------------- |
+| `server.ts` | the tables (state that survives every code change) and the tools Bots call |
+| `ui.tsx`    | the page the User sees beside the conversation                             |
+
+## The loop
+
+```sh
+applet check # type-check and lint; every problem prints as path:line:col message
+applet build # dist/server.js, dist/ui.html, dist/manifest.json
+applet dev   # serves the built Applet; prints a URL, opens nothing
+```
+
+Open the printed URL in the Computer's browser to look at it. Publish with
+`applet_publish` once `applet check` is clean.
+
+## Rules the linter enforces
+
+- Colours come from the nine `--frockbot-*` theme tokens. The kit's components
+  already use them; never write `#hex`, `rgb(...)`, or a colour name.
+- No `fetch`, `XMLHttpRequest`, or `WebSocket`. The Applet has no outbound
+  network: reach the world through a tool on the server.
+- Import only from `@frockbot/applet-sdk/*`, `react`, and your own files.
+- Declare tables with `table({ ... })` and tools with `this.tool({ ... }, fn)`.
+
+## Changing the schema
+
+Add a column with `.default(...)` or `.optional()` and the SDK adds it on the
+next mount, keeping the rows. For anything else — renaming, rewriting values —
+override `migrate(from)` on the class; it runs once, before the Applet serves
+anything, and throwing fails the mount back to the last known-good generation.
+
+The kit's components and their props are documented in the Applets Skill.

package/template/applet.json

@@ -0,0 +1,5 @@
+{
+  "id": "__APPLET_ID__",
+  "displayName": "__APPLET_NAME__",
+  "contract": 1
+}

package/template/server.ts

@@ -0,0 +1,46 @@
+import { Applet, t, table } from "@frockbot/applet-sdk/server";
+
+/**
+ * The schema. It becomes the SQLite tables, the wire format, and the client's
+ * collections, and it survives every publish: changing this file's code never
+ * clears the rows.
+ */
+const tables = {
+  todos: table({
+    id: t.id(),
+    title: t.text(),
+    done: t.boolean().default(false),
+    createdAt: t.timestamp(),
+  }),
+};
+
+/**
+ * The server half of __APPLET_NAME__.
+ *
+ * `tools` is what every Bot of this User can call. `this.db` is the only way
+ * to read or write, and each call is atomic.
+ */
+export default class TodoApplet extends Applet<typeof tables> {
+  tables = tables;
+
+  tools = {
+    add_todo: this.tool(
+      { description: "Add a todo to the list", input: { title: t.text() } },
+      ({ title }) => {
+        this.db.todos.insert({ title, createdAt: new Date().toISOString() });
+        return `Added "${title}".`;
+      },
+    ),
+    list_todos: this.tool(
+      { description: "List the todos, open ones first", input: {} },
+      () => {
+        const todos = this.db.todos.select();
+        if (todos.length === 0) return "The list is empty.";
+        return todos
+          .sort((left, right) => Number(left.done) - Number(right.done))
+          .map((todo) => `${todo.done ? "[x]" : "[ ]"} ${todo.title}`)
+          .join("\n");
+      },
+    ),
+  };
+}

package/template/ui.tsx

@@ -0,0 +1,113 @@
+import { useState } from "react";
+import { createApplet, mount, newId } from "@frockbot/applet-sdk/client";
+import {
+  Button,
+  Checkbox,
+  EmptyState,
+  Input,
+  List,
+  ListItem,
+  Stack,
+  Text,
+  Toolbar,
+} from "@frockbot/applet-sdk/kit";
+
+import type TodoApplet from "./server";
+
+/**
+ * The page half of __APPLET_NAME__.
+ *
+ * `createApplet` connects when the host sends its `init` message, so there is
+ * no loading wiring to write. Every mutation is optimistic: the row appears at
+ * once and rolls back on its own if the server rejects it.
+ */
+const applet = createApplet<TodoApplet>();
+
+function App() {
+  const [draft, setDraft] = useState("");
+  const { status } = applet.useApplet();
+  const { data: todos } = applet.useLiveQuery((query) =>
+    query
+      .from({ todo: applet.tables.todos })
+      .orderBy(({ todo }) => todo.createdAt),
+  );
+
+  const add = () => {
+    const title = draft.trim();
+    if (title === "") return;
+    applet.tables.todos.insert({
+      id: newId(),
+      title,
+      done: false,
+      createdAt: new Date().toISOString(),
+    });
+    setDraft("");
+  };
+
+  return (
+    <Stack root gap="large">
+      <Toolbar
+        end={
+          <Text size="small" tone="muted">
+            {status}
+          </Text>
+        }
+      >
+        <Text size="title">__APPLET_NAME__</Text>
+      </Toolbar>
+
+      <Stack direction="row" gap="small" align="end">
+        <Input
+          label="New todo"
+          value={draft}
+          placeholder="Buy milk"
+          onValueChange={setDraft}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") add();
+          }}
+        />
+        <Button variant="primary" onClick={add}>
+          Add
+        </Button>
+      </Stack>
+
+      {todos.length === 0 ? (
+        <EmptyState
+          title="Nothing yet"
+          description="Add your first todo above."
+        />
+      ) : (
+        <List>
+          {todos.map((todo) => (
+            <ListItem
+              key={todo.id}
+              start={
+                <Checkbox
+                  checked={todo.done}
+                  ariaLabel={`Mark "${todo.title}" done`}
+                  onChange={(done) =>
+                    applet.tables.todos.update(todo.id, (draftRow) => {
+                      draftRow.done = done;
+                    })
+                  }
+                />
+              }
+              end={
+                <Button
+                  variant="ghost"
+                  onClick={() => applet.tables.todos.delete(todo.id)}
+                >
+                  Delete
+                </Button>
+              }
+            >
+              <Text tone={todo.done ? "muted" : "default"}>{todo.title}</Text>
+            </ListItem>
+          ))}
+        </List>
+      )}
+    </Stack>
+  );
+}
+
+mount(<App />);

package/types/cloudflare-workers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The only part of the Cloudflare programming model the SDK names.
+ *
+ * ADR 0022 records the ceiling deliberately: 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;
+  };
+};