@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/examples/reference-service/README.md

@@ -0,0 +1,33 @@
+# Reference service
+
+A small shop built on `@aotter/mantle` 0.2.0. It is also the Worker that the
+release gate runs (`scripts/check-worker-consumer.mjs`).
+
+- `manifests/`: the whole service in the v2 grammar.
+  - A scoped Schema (`orders`) and a Schema with a check (`items`, `stock >= 0`).
+  - Views written as one `SELECT`: a join, a `GROUP BY`, and `mantle.search`.
+  - Procedures written as SQL: a two-statement order, an `ON CONFLICT`
+    restock, and an optimistic-lock cancel in handler code.
+  - An after hook that loops over `ctx.cause.rows`.
+  - A POSIX cron.
+- `src/handlers.ts`: the three `ref` handlers, written against the typed
+  `ctx.store`.
+- `src/service.ts`, `src/index.ts`, `wrangler.jsonc`, `tsconfig.json`: the
+  preset `mantle generate` wrote once. These files are the application's own.
+- `smoke.mjs`: starts `wrangler dev` on a fresh local D1 and drives the service:
+  - console email-OTP sign-in for an owner and a buyer;
+  - REST, both MCP surfaces, the cron, and Admin: the console from `@aotter/mantle-ui/admin` at `/admin`, its API, and an editor's save;
+  - asserts scope, the stock check, locks and hooks.
+
+Outside the SDK workspace, with Node 22+ and pnpm 9+, pin every dependency to
+one exact version, then:
+
+```sh
+pnpm install
+pnpm check                      # generate, generate --check, typecheck, smoke
+cp .dev.vars.example .dev.vars  # set ADMIN_EMAIL and a random BETTER_AUTH_SECRET
+pnpm dev                        # open /admin; sign-in codes are printed to this log
+```
+
+The release gate installs the exact tarballs it just packed in place of the
+pinned versions.

package/docs/examples/reference-service/manifests/catalog.yaml

@@ -0,0 +1,103 @@
+# A small shop: a public catalog, orders that only their owner sees, and staff tools.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: items }
+spec:
+  title: Items
+  lifecycle: operational
+  schema:
+    type: object
+    required: [sku, name, stock]
+    properties:
+      sku: { type: string }
+      name: { type: string }
+      priceCents: { type: integer, minimum: 0 }
+      stock: { type: integer, default: 0 }
+  checks: ["stock >= 0"]
+  uiSchema: { list: { primaryField: name, columns: [sku, stock] } }
+  uniqueIndexes: [[sku]]
+  searchableFields: [name, sku]
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: orders }
+spec:
+  title: Orders
+  lifecycle: operational
+  scope: { owner: auth.uid() }
+  uiSchema: { list: { primaryField: itemId, columns: [qty, orderStatus] } }
+  indexes: [[owner]]
+  schema:
+    type: object
+    required: [owner, itemId, qty, orderStatus]
+    properties:
+      owner: { type: string }
+      itemId: { type: string }
+      qty: { type: integer, minimum: 1 }
+      orderStatus: { type: string, enum: [placed, cancelled] }
+      placedAt: { type: string, format: date-time }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: activity }
+spec:
+  title: Activity
+  lifecycle: operational
+  schema:
+    type: object
+    required: [kind, subject]
+    properties:
+      kind: { type: string }
+      subject: { type: string }
+      detail: { type: string }
+---
+# Views are one SELECT; `input` is their parameters.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: catalog }
+spec:
+  surface: public
+  sql: SELECT id, sku, name, priceCents, stock FROM items ORDER BY name
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: search-items }
+spec:
+  surface: public
+  input: { type: object, required: [q], properties: { q: { type: string, minLength: 1 } } }
+  sql: |
+    SELECT i.id, i.name, i.stock FROM items i
+    WHERE mantle.search(i, input.q)
+    ORDER BY mantle.search_rank(i), i.name
+---
+# Scope is injected into every Schema reference: this join only ever sees the caller's orders.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: my-orders }
+spec:
+  surface: public
+  requires: { auth: { all: [ctx.user] } }
+  sql: |
+    SELECT o.id, o.qty, o.orderStatus, i.name AS item, o.version
+    FROM orders o JOIN items i ON i.id = o.itemId
+    ORDER BY o.created_at DESC
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: sales-by-item }
+spec:
+  surface: staff
+  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
+  sql: |
+    SELECT i.name, count(o.id) AS orders, coalesce(sum(o.qty), 0) AS units
+    FROM items i LEFT JOIN orders o ON o.itemId = i.id AND o.orderStatus = 'placed'
+    GROUP BY i.name
+    ORDER BY units DESC, i.name
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: recent-activity }
+spec:
+  surface: staff
+  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
+  sql: SELECT kind, subject, detail FROM activity ORDER BY created_at DESC LIMIT 50

package/docs/examples/reference-service/manifests/orders.yaml

@@ -0,0 +1,120 @@
+# A Procedure written as SQL: its statements apply together or not at all. The order is written
+# first, so when the stock check on items fails the second statement, the order is rolled back too.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: place-order }
+spec:
+  title: Place an order
+  description: Order one item for the signed-in caller; the stock check fails the whole order when stock runs out.
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    required: [itemId, qty]
+    properties:
+      itemId: { type: string }
+      qty: { type: integer, minimum: 1 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO orders (itemId, qty, orderStatus, placedAt)
+      SELECT id, input.qty, 'placed', now() FROM items WHERE id = input.itemId
+      RETURNING id, qty, orderStatus;
+      UPDATE items SET stock = stock - input.qty WHERE id = input.itemId
+---
+# Optimistic concurrency: the caller sends the version it saw.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: cancel-order }
+spec:
+  title: Cancel an order
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    required: [orderId, expectedVersion]
+    properties:
+      orderId: { type: string }
+      expectedVersion: { type: integer }
+  output: { type: object }
+  handler: { ref: cancelOrder }
+---
+# An upsert keyed by a unique index.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: restock }
+spec:
+  title: Restock an item
+  description: Add stock to an item by SKU, creating the item if it is new.
+  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
+  input:
+    type: object
+    required: [sku, name, qty]
+    properties:
+      sku: { type: string }
+      name: { type: string }
+      qty: { type: integer, minimum: 1 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO items (sku, name, stock) VALUES (input.sku, input.name, input.qty)
+      ON CONFLICT (sku) DO UPDATE SET stock = items.stock + EXCLUDED.stock
+      RETURNING id, sku, stock
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: record-orders }
+spec:
+  input: { type: object }
+  output: { type: object }
+  handler: { ref: recordOrders }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: weekly-digest }
+spec:
+  input: { type: object }
+  output: { type: object }
+  handler: { ref: weeklyDigest }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: place-order-http }
+spec:
+  source: { kind: http, method: POST, path: /api/orders }
+  target: { procedure: place-order }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: place-order-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: place-order }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: cancel-order-http }
+spec:
+  source: { kind: http, method: POST, path: /api/orders/cancel }
+  target: { procedure: cancel-order }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: restock-mcp }
+spec:
+  source: { kind: mcp, surface: staff }
+  target: { procedure: restock }
+---
+# After hooks get every row one statement touched.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: orders-recorded }
+spec:
+  source: { kind: lifecycle, schema: orders, on: [after_create, after_update] }
+  target: { procedure: record-orders }
+---
+# POSIX cron, UTC: Sundays at 03:00.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: weekly-digest }
+spec:
+  source: { kind: schedule, cron: "0 3 * * 0" }
+  target: { procedure: weekly-digest }

package/docs/examples/reference-service/mantle.config.json

@@ -0,0 +1 @@
+{ "version": 2, "identity": "mantle", "features": ["mcp", "admin", "web"] }

package/docs/examples/reference-service/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "mantle-reference-service",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate": "mantle generate",
+    "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
+    "check": "mantle generate && mantle generate --check && tsc --noEmit && node smoke.mjs"
+  },
+  "dependencies": {
+    "@aotter/mantle": "0.2.0-alpha.1",
+    "@aotter/mantle-ui": "0.2.0-alpha.1",
+    "@better-auth/cimd": "1.7.2",
+    "@better-auth/mcp": "1.7.2",
+    "@better-auth/oauth-provider": "1.7.2",
+    "@modelcontextprotocol/ext-apps": "2.0.0",
+    "@modelcontextprotocol/server": "2.1.0",
+    "better-auth": "1.7.2"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "5.20260904.1",
+    "@types/node": "^26",
+    "typescript": "^6.0.3",
+    "wrangler": "4.129.0"
+  },
+  "packageManager": "pnpm@9.15.0"
+}

package/docs/examples/reference-service/smoke.mjs

@@ -0,0 +1,156 @@
+// Runs the service under `wrangler dev` on a fresh local D1 and drives it the way people and agents would: console email-OTP
+// sign-in, REST, both MCP surfaces, Admin's API and a cron. Each step asserts what the manifests promise.
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const port = 18000 + Math.floor(Math.random() * 1000);
+const origin = `http://127.0.0.1:${port}`;
+const owner = "owner@example.test";
+const state = mkdtempSync(join(tmpdir(), "mantle-reference-"));
+const wrangler = spawn("pnpm", ["exec", "wrangler", "dev", "--local", "--ip", "127.0.0.1", "--port", String(port), "--inspector-port", "0",
+  "--persist-to", state, "--test-scheduled",
+  "--var", `PUBLIC_ORIGIN:${origin}`, "--var", `ADMIN_EMAIL:${owner}`, "--var", "BETTER_AUTH_SECRET:reference-smoke-secret-0123456789abcdef"],
+// its own process group: pnpm does not pass a signal on to wrangler and workerd, so the group is stopped as one
+{ env: { ...process.env, WRANGLER_SEND_METRICS: "false", CI: "1" }, stdio: ["ignore", "pipe", "pipe"], detached: true });
+let logs = "";
+wrangler.stdout.on("data", (chunk) => { logs += chunk; });
+wrangler.stderr.on("data", (chunk) => { logs += chunk; });
+
+const json = { "content-type": "application/json", origin };
+const call = async (method, path, { cookie, body } = {}) => {
+  const response = await fetch(`${origin}${path}`, { method, headers: { ...json, ...(cookie ? { cookie } : {}) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+  const text = await response.text();
+  return { status: response.status, body: text ? JSON.parse(text) : null, headers: response.headers };
+};
+const mcp = async (path, cookie, name, args) => {
+  const response = await fetch(`${origin}${path}`, { method: "POST", headers: { ...json, accept: "application/json, text/event-stream", ...(cookie ? { cookie } : {}) },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: name ? "tools/call" : "tools/list", params: name ? { name, arguments: args } : {} }) });
+  const text = await response.text();
+  const data = text.split("\n").find((line) => line.startsWith("data:"));
+  return { status: response.status, body: data ? JSON.parse(data.slice(5)) : text ? JSON.parse(text) : null };
+};
+
+/** Console email OTP: ask for a code, read it from the wrangler log as a developer would, sign in. */
+async function signIn(email) {
+  const before = logs.length;
+  assert.equal((await call("POST", "/api/auth/email-otp/send-verification-otp", { body: { email, type: "sign-in" } })).status, 200);
+  let code;
+  for (let i = 0; i < 40 && !code; i++) {
+    code = new RegExp(`${email.replace(/[.+]/g, "\\$&")}[\\s\\S]*?one-time code is (\\d{6})`).exec(logs.slice(before))?.[1];
+    if (!code) await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  assert.ok(code, `no one-time code for ${email} in the log`);
+  const signed = await call("POST", "/api/auth/sign-in/email-otp", { body: { email, otp: code } });
+  assert.equal(signed.status, 200, JSON.stringify(signed.body));
+  return signed.headers.getSetCookie().map((c) => c.split(";")[0]).join("; ");
+}
+
+const stockOf = async () => (await call("GET", "/api/views/catalog")).body.rows[0].stock;
+const step = (name) => console.log(`ok - ${name}`);
+
+try {
+  for (let attempt = 0; ; attempt++) {
+    if (wrangler.exitCode !== null) throw new Error(`wrangler exited ${wrangler.exitCode}`);
+    try { if ((await fetch(`${origin}/api/views/catalog`)).status === 200) break; } catch { /* starting */ }
+    if (attempt > 240) throw new Error("the Worker did not start");
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  assert.deepEqual((await call("GET", "/api/views/catalog")).body.rows, []);
+  step("boot converges a fresh D1 to the plan; the public catalog is empty");
+
+  const staff = await signIn(owner);
+  assert.equal((await call("GET", "/admin/api/me", { cookie: staff })).body.role, "owner");
+  step("console email OTP signs in; ADMIN_EMAIL becomes the owner");
+
+  for (const qty of [5, 3]) {
+    const restocked = await mcp("/mcp/staff", staff, "restock", { sku: "TEA-1", name: "Oolong tea", qty });
+    assert.equal(restocked.body.result.isError, undefined, JSON.stringify(restocked.body));
+  }
+  assert.equal(await stockOf(), 8);
+  step("staff MCP: restock is an upsert on the unique sku (5 + 3)");
+
+  const itemId = (await call("GET", "/api/views/catalog")).body.rows[0].id;
+  assert.equal((await call("POST", "/api/orders", { body: { itemId, qty: 1 } })).status, 401);
+  step("an anonymous order is 401");
+
+  const buyer = await signIn("buyer@example.test");
+  assert.equal((await call("GET", "/admin/api/me", { cookie: buyer })).status, 403);
+  const placed = await call("POST", "/api/orders", { cookie: buyer, body: { itemId, qty: 2 } });
+  assert.equal(placed.status, 200, JSON.stringify(placed.body));
+  assert.equal(await stockOf(), 6);
+  step("a signed-in buyer (not staff) orders 2: stock 8 -> 6 in one program");
+
+  const tooMany = await call("POST", "/api/orders", { cookie: buyer, body: { itemId, qty: 99 } });
+  assert.equal(tooMany.status, 400, JSON.stringify(tooMany.body));
+  assert.match(tooMany.body.error.message, /CHECK items: stock >= 0/);
+  assert.equal(await stockOf(), 6);
+  step("ordering 99 fails the stock >= 0 check in the second statement, and the order the first wrote is rolled back");
+
+  const mine = (await call("GET", "/api/views/my-orders", { cookie: buyer })).body.rows;
+  assert.deepEqual(mine.map(({ qty, orderStatus, item }) => ({ qty, orderStatus, item })), [{ qty: 2, orderStatus: "placed", item: "Oolong tea" }]);
+  assert.deepEqual((await call("GET", "/api/views/my-orders", { cookie: staff })).body.rows, []);
+  step("my-orders joins items and shows only the caller's own orders (scope)");
+
+  const order = mine[0];
+  assert.equal((await call("POST", "/api/orders/cancel", { cookie: staff, body: { orderId: order.id, expectedVersion: order.version } })).status, 409);
+  const cancelled = await call("POST", "/api/orders/cancel", { cookie: buyer, body: { orderId: order.id, expectedVersion: order.version } });
+  assert.equal(cancelled.status, 200, JSON.stringify(cancelled.body));
+  assert.equal(await stockOf(), 8);
+  assert.equal((await call("POST", "/api/orders/cancel", { cookie: buyer, body: { orderId: order.id, expectedVersion: order.version } })).status, 409);
+  step("cancel: another owner's order is a CONFLICT, the owner's returns the stock, a stale version is a CONFLICT");
+
+  assert.deepEqual((await call("GET", "/api/views/search-items?q=oolong")).body.rows.map((r) => r.name), ["Oolong tea"]);
+  step("search-items: mantle.search over searchableFields");
+
+  const sales = await call("GET", "/admin/api/views/sales-by-item", { cookie: staff });
+  assert.deepEqual(sales.body.rows, [{ name: "Oolong tea", orders: 0, units: 0 }], JSON.stringify(sales.body));
+  assert.equal((await call("GET", "/admin/api/views/sales-by-item", { cookie: buyer })).status, 403);
+  step("sales-by-item (GROUP BY over a LEFT JOIN) is staff-only through Admin's API");
+
+  // the console: @aotter/mantle-ui/admin served by Admin at /admin, its assets by name, any other path its client-side route
+  const shell = await fetch(`${origin}/admin/c/items`);
+  const html = await shell.text();
+  const script = /src="(\/admin\/assets\/[^"]+\.js)"/.exec(html)?.[1];
+  assert.equal(shell.headers.get("x-frame-options"), "DENY");
+  assert.ok(script, html.slice(0, 300));
+  assert.equal((await fetch(`${origin}${script}`)).status, 200);
+  assert.equal((await fetch(`${origin}/admin/assets/missing.js`)).status, 404);
+  // the editor's round trip: it reads the whole entry and writes it back, an unset optional field included as null
+  const [tea] = (await call("GET", "/admin/api/entries?collection=items", { cookie: staff })).body.items;
+  assert.deepEqual(tea.data_preview, { name: "Oolong tea", sku: "TEA-1", stock: 8 });
+  const { entry } = (await call("GET", `/admin/api/entries/${tea.id}?collection=items`, { cookie: staff })).body;
+  const saved = await call("PATCH", `/admin/api/entries/${tea.id}?collection=items`, { cookie: staff, body: { expectedVersion: entry.version, data: { ...entry.data, name: "Oolong tea (Taiwan)", priceCents: null } } });
+  assert.equal(saved.status, 200, JSON.stringify(saved.body));
+  assert.equal((await call("GET", "/api/views/catalog")).body.rows[0].name, "Oolong tea (Taiwan)");
+  step("Admin's console: the SPA and its assets at /admin, the list's declared columns, and an editor's save of the whole entry");
+
+  const tools = (await mcp("/mcp", undefined)).body.result.tools.map((t) => t.name);
+  assert.ok(tools.includes("place_order") && !tools.includes("restock"), tools.join());
+  step("public MCP lists place_order and not the staff restock");
+
+  assert.equal((await fetch(`${origin}/__scheduled?cron=${encodeURIComponent("0 3 * * 1")}`)).status, 200);
+  const activity = (await call("GET", "/admin/api/views/recent-activity", { cookie: staff })).body.rows;
+  assert.deepEqual(activity.map((r) => r.kind).sort(), ["after_create", "after_update", "weekly-digest"]);
+  // the one order was cancelled, and the digest counts placed orders only
+  assert.equal(activity.find((r) => r.kind === "weekly-digest").detail, "0 orders, 0 units");
+  step("the after hooks recorded the order rows, and Cloudflare's Monday-numbered cron ran the POSIX Sunday digest");
+
+  const version = JSON.parse(readFileSync("node_modules/@aotter/mantle/package.json", "utf8")).version;
+  console.log(`Mantle ${version}: reference service passed`);
+} catch (error) {
+  console.error(logs.slice(-4000));
+  throw error;
+} finally {
+  const stop = (signal) => { try { process.kill(-wrangler.pid, signal); } catch { /* already gone */ } };
+  stop("SIGTERM");
+  await new Promise((resolve) => {
+    if (wrangler.exitCode !== null) return resolve();
+    const timer = setTimeout(() => { stop("SIGKILL"); resolve(); }, 5_000);
+    wrangler.once("exit", () => { clearTimeout(timer); resolve(); });
+  });
+  stop("SIGKILL");
+  rmSync(state, { recursive: true, force: true });
+}

package/docs/examples/reference-service/src/handlers.ts

@@ -0,0 +1,36 @@
+// Written once by `mantle generate`, then filled in. `MantleHandlers` lists exactly the plan's handler refs.
+import type { MantleHandlers } from "../.mantle/generated/mantle.js";
+
+export const handlers: MantleHandlers = {
+  // ctx.store is scoped to the caller: another owner's order is not visible, so the write below is a CONFLICT, never a leak
+  cancelOrder: async ({ orderId, expectedVersion }, ctx) => {
+    const [order] = (await ctx.store.select({ from: "orders", where: { id: orderId, orderStatus: "placed" } })).rows;
+    const [item] = order ? (await ctx.store.select({ from: "items", where: { id: String(order.itemId) } })).rows : [];
+    await ctx.store.write([
+      { update: "orders", set: { orderStatus: "cancelled" }, where: { id: orderId }, lock: expectedVersion },
+      // both rows or neither: the stock goes back only with the cancellation, and a concurrent restock is a CONFLICT
+      ...(order && item ? [{ update: "items" as const, set: { stock: Number(item.stock) + Number(order.qty) }, where: { id: String(item.id) }, lock: Number(item.version) }] : []),
+    ]);
+    return { id: orderId, orderStatus: "cancelled" };
+  },
+
+  // an after hook gets every row the statement touched: loop, never rows[0]
+  recordOrders: async (_input, ctx) => {
+    const cause = ctx.cause;
+    if (cause.kind !== "lifecycle") return {};
+    await ctx.store.write(cause.rows.map((row) => ({
+      insert: "activity" as const,
+      values: { kind: cause.hook, subject: String(row.id), detail: `${String(row.orderStatus)} x${String(row.qty)}` },
+    })));
+    return {};
+  },
+
+  // a schedule runs as the system caller: no scope, and no requires.auth predicate holds for it. One page of up to 500 orders
+  // keeps the example short; a digest over more would page with nextCursor.
+  weeklyDigest: async (_input, ctx) => {
+    const { rows } = await ctx.store.select({ from: "orders", columns: ["qty"], where: { orderStatus: "placed" }, limit: 500 });
+    const units = rows.reduce((sum, row) => sum + Number(row.qty), 0);
+    await ctx.store.write([{ insert: "activity", values: { kind: "weekly-digest", subject: String(ctx.cause.kind === "schedule" ? ctx.cause.scheduledTime : ""), detail: `${rows.length} orders, ${units} units` } }]);
+    return {};
+  },
+};

package/docs/examples/reference-service/src/index.ts

@@ -0,0 +1,33 @@
+// Written once by `mantle generate`; this file is yours now. The Cloudflare entry (ADR-0032 decision 6).
+import { waitUntil } from "cloudflare:workers";
+import { toCloudflareCron } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+import { mantle, type Env } from "./service.js";
+
+// Cloudflare names a cron as wrangler.jsonc spells it; the plan's schedule Triggers are POSIX, and several spellings can share one
+const crons = new Map<string, string[]>();
+for (const t of Object.values(plan.triggers)) {
+  if (t.source.kind !== "schedule" || t.source.enabled === false) continue;
+  const cf = toCloudflareCron(t.source.cron);
+  const posix = crons.get(cf) ?? [];
+  if (!posix.includes(t.source.cron)) crons.set(cf, [...posix, t.source.cron]);
+}
+// not bound to one request, so a handler's ctx.waitUntil never lands on another request's finished context
+const ctx = { waitUntil };
+
+export default {
+  fetch: (request, env) => mantle.fetch(request, env, ctx),
+  async scheduled(controller, env) {
+    const posix = crons.get(controller.cron);
+    if (posix === undefined) throw new Error(`No schedule Trigger runs on the Cloudflare cron '${controller.cron}'`);
+    const errors: unknown[] = [];
+    for (const cron of posix) {
+      try {
+        await mantle.invokeSchedule(cron, controller.scheduledTime, env, ctx);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length) throw new AggregateError(errors, `${errors.length} cron spelling(s) failed for '${controller.cron}'`);
+  },
+} satisfies ExportedHandler<Env>;

package/docs/examples/reference-service/src/service.ts

@@ -0,0 +1,78 @@
+// Written once by `mantle generate`; this file is yours now. It composes the service (ADR-0032 decision 6).
+import { createMantle, withCaller, type MantleRuntime, type MantleService, type Surface } from "@aotter/mantle";
+import { createAdminSurface } from "@aotter/mantle/admin";
+import { ConsoleEmailSender, createAuthRoutes, createCallerResolver, createMantleAuth, createSetupIncompleteAuth, type MantleAuth } from "@aotter/mantle/auth";
+import { d1Driver, d1Storage } from "@aotter/mantle/cloudflare";
+import { createMcpSurface, planApp } from "@aotter/mantle/mcp";
+import { mantleAppHtml } from "@aotter/mantle-ui/mcp-app";
+import { createRestSurface } from "@aotter/mantle/web";
+import { plan } from "../.mantle/generated/mantle.js";
+import { handlers } from "./handlers.js";
+
+export interface Env {
+  readonly DB: D1Database;
+  /** The Admin SPA's files (`@aotter/mantle-ui/admin`), bound in wrangler.jsonc. */
+  readonly ASSETS: Fetcher;
+  readonly BETTER_AUTH_SECRET?: string;
+  readonly PUBLIC_ORIGIN?: string;
+  readonly ADMIN_EMAIL?: string;
+}
+
+/** One-time codes printed to the log are for local development: a deployed service picks its own sign-in method and sender. */
+function createAuth(env: Env, origin: string): MantleAuth {
+  // an unset PUBLIC_ORIGIN is not local: the fallback origin below is only for URLs, never for deciding to print codes
+  const local = env.PUBLIC_ORIGIN !== undefined && /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(origin);
+  if (!local || !env.BETTER_AUTH_SECRET || !env.ADMIN_EMAIL)
+    return createSetupIncompleteAuth({ message: "Sign-in is not configured: copy .dev.vars.example to .dev.vars locally, or choose a sign-in method in src/service.ts." });
+  return createMantleAuth({
+    database: env.DB, driver: d1Driver(env.DB), baseURL: origin, secret: env.BETTER_AUTH_SECRET,
+    methods: [{ kind: "email-otp", sender: new ConsoleEmailSender() }],
+    bootstrapOwner: { match: "email", value: env.ADMIN_EMAIL },
+    ipAddressHeaders: ["cf-connecting-ip"],
+    oauthProvider: { loginPage: "/admin/sign-in", consentPage: "/oauth/consent", scopes: ["mcp"], mcpResource: `${origin}/mcp` },
+  });
+}
+
+/** A file of the Admin SPA, or null when it has none by that path. */
+async function adminAsset(assets: Fetcher, path: string): Promise<Response | null> {
+  const response = await assets.fetch(new URL(path, "http://assets/"));
+  return response.ok ? response : null;
+}
+
+function mount(runtime: MantleRuntime, env: Env) {
+  const origin = env.PUBLIC_ORIGIN?.replace(/\/+$/, "") ?? "http://127.0.0.1:8787";
+  const auth = createAuth(env, origin);
+  const resolver = createCallerResolver(auth, { jwtBearer: { audience: `${origin}/mcp`, scopes: ["mcp"] } });
+  const authRoutes = createAuthRoutes(auth, { resolver });
+  const guard = (surface: Surface, options?: { resourceMetadata?: string }) => withCaller(resolver, surface, options);
+  const resourceMetadata = `${origin}/.well-known/oauth-protected-resource/mcp`;
+  const admin = guard(createAdminSurface(runtime, { basePath: "/admin", assets: (path) => adminAsset(env.ASSETS, path), identity: { directory: auth, roles: auth, deleteUser: auth.deleteUser }, site: { mcpEndpoints: { public: "/mcp", staff: "/mcp/staff" } } }));
+  const mcp = guard(createMcpSurface(runtime, { basePath: "/mcp", surface: "public", resourceMetadata }), { resourceMetadata });
+  // MCP Apps hosts render each staff View's rows, and the operations on one row, in the chat
+  const staffMcp = guard(createMcpSurface(runtime, { basePath: "/mcp/staff", surface: "staff", apps: { resources: [planApp(runtime.plan, { surface: "staff", html: mantleAppHtml })] }, resourceMetadata }), { resourceMetadata });
+  // REST answers everything else: public Views under /api/views and the plan's HTTP Triggers
+  const rest = guard(createRestSurface(runtime, { basePath: "/api" }));
+  return async (request: Request, waitUntil: (promise: Promise<unknown>) => void): Promise<Response> => {
+    const { pathname } = new URL(request.url);
+    const under = (base: string) => pathname === base || pathname.startsWith(`${base}/`);
+    // Better Auth's context is per isolate: the request that starts it waits for it, or the next one hangs on it; a failed start is mounted again
+    await auth.ready?.catch((error) => {
+      routes = undefined;
+      throw error;
+    });
+    const owned = await authRoutes(request, { waitUntil });
+    if (owned) return owned;
+    if (under("/admin")) return admin(request);
+    if (under("/mcp/staff")) return staffMcp(request);
+    if (under("/mcp")) return mcp(request);
+    return rest(request);
+  };
+}
+
+let routes: ReturnType<typeof mount> | undefined;
+const service: MantleService<Env> = {
+  handlers,
+  fetch: (request, env, { runtime, waitUntil }) => (routes ??= mount(runtime, env))(request, waitUntil),
+};
+
+export const mantle = createMantle(service, { plan, storage: (env) => d1Storage(env.DB), schedules: true });

package/docs/examples/{host-minimal-worker → reference-service}/tsconfig.json

@@ -1,13 +1,18 @@
 {
   "compilerOptions": {
     "target": "ES2022",
+    "lib": [
+      "ES2023"
+    ],
     "module": "ESNext",
-    "moduleResolution": "bundler",
+    "moduleResolution": "Bundler",
     "strict": true,
     "noEmit": true,
     "skipLibCheck": true,
+    "resolveJsonModule": true,
     "types": [
-      "@cloudflare/workers-types"
+      "@cloudflare/workers-types",
+      "node"
     ]
   },
   "include": [

package/docs/examples/reference-service/wrangler.jsonc

@@ -0,0 +1,26 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mantle-reference",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-09-01",
+  "compatibility_flags": [
+    "nodejs_compat"
+  ],
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "mantle-reference"
+    }
+  ],
+  "assets": {
+    "directory": "node_modules/@aotter/mantle-ui/dist/admin",
+    "binding": "ASSETS",
+    "run_worker_first": true,
+    "html_handling": "none"
+  },
+  "triggers": {
+    "crons": [
+      "0 3 * * 1"
+    ]
+  }
+}