@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

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

@@ -1,33 +0,0 @@
-# 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

@@ -1,103 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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

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

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

@@ -1,27 +0,0 @@
-{
-  "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.5",
-    "@aotter/mantle-ui": "0.2.0-alpha.5",
-    "@better-auth/cimd": "1.7.7",
-    "@better-auth/mcp": "1.7.7",
-    "@better-auth/oauth-provider": "1.7.7",
-    "@modelcontextprotocol/ext-apps": "2.0.0",
-    "@modelcontextprotocol/server": "2.1.0",
-    "better-auth": "1.7.7"
-  },
-  "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

@@ -1,160 +0,0 @@
-// 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];
-  const base = /<base href="([^"]+)"/.exec(html)?.[1] ?? "/admin/";
-  assert.equal(shell.headers.get("x-frame-options"), "DENY");
-  assert.ok(script, html.slice(0, 300));
-  const scriptUrl = new URL(script, new URL(base, origin));
-  assert.equal(scriptUrl.origin, origin);
-  assert.ok(scriptUrl.pathname.startsWith("/admin/assets/"));
-  assert.equal((await fetch(scriptUrl)).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

@@ -1,36 +0,0 @@
-// 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

@@ -1,33 +0,0 @@
-// 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

@@ -1,78 +0,0 @@
-// 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: "/admin/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/reference-service/wrangler.jsonc

@@ -1,26 +0,0 @@
-{
-  "$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"
-    ]
-  }
-}