@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/usecase/validation.js

@@ -0,0 +1,233 @@
+/** Compile boundary checks into each operation; no schema enters the request bundle. */
+import { INPUT_RULE_KEYWORDS, lookupLocalRef as lookup, rootRefChain } from "../build/compiler.js";
+import { literal, q } from "../domain/entry.js";
+import { publishingInput } from "./publishing.js";
+import { equal } from "../kernel/validation.js";
+const pointer = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
+const supported = new Set([..."$defs $ref $schema $id type nullable properties required additionalProperties items enum const format pattern minLength maxLength minimum maximum exclusiveMinimum exclusiveMaximum multipleOf minItems maxItems title description default readOnly writeOnly examples deprecated x-mantle-ref x-mcp-hint".split(" "), ...INPUT_RULE_KEYWORDS]);
+const shapes = "see docs/handbook/reference/surface.md";
+// YAML .inf and .nan parse to numbers that JSON writes as null.
+const finite = (value) => typeof value === "number" ? Number.isFinite(value) : !!value && typeof value === "object" ? Object.values(value).every(finite) : true;
+const has = (key) => `Object.hasOwn(object,${q(key)})`;
+const exactly = (value, keys) => !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).sort().join(" ") === keys;
+/**
+ * An object schema's rules, each failing `when` (JavaScript on `object`) with its sentence at the missing field `key`, or the
+ * reason a rule has an unsupported shape.
+ */
+function rules(schema) {
+    const declared = (names) => Array.isArray(names) && names.length > 0 && names.every(name => typeof name === "string" && Object.hasOwn(schema.properties ?? {}, name));
+    const list = (names) => names.map(name => `'${name}'`).join(" and ");
+    const found = [], { dependentRequired: dependent, anyOf, if: condition, then, else: otherwise } = schema;
+    if (dependent !== undefined) {
+        if (!dependent || typeof dependent !== "object" || Array.isArray(dependent) || !declared(Object.keys(dependent)) || !Object.values(dependent).every(declared))
+            return `dependentRequired maps declared properties to lists of declared properties; ${shapes}.`;
+        for (const [key, names] of Object.entries(dependent))
+            for (const name of names)
+                found.push({ when: `${has(key)} && !${has(name)}`, key: name, message: `'${name}' is required when '${key}' is present.` });
+    }
+    if (anyOf !== undefined) {
+        if (!Array.isArray(anyOf) || !anyOf.length || !anyOf.every(branch => exactly(branch, "required") && declared(branch.required)))
+            return `anyOf is supported only as branches of exactly { required: [declared properties] }; ${shapes}.`;
+        const branches = anyOf.map(branch => branch.required);
+        found.push({ when: `!(${branches.map(names => names.map(has).join(" && ")).join(" || ")})`, message: `At least one of ${branches.map(names => names.length > 1 ? `(${list(names)})` : list(names)).join(", ")} is required.` });
+    }
+    if (condition !== undefined || then !== undefined || otherwise !== undefined) {
+        const [key] = exactly(condition, "properties required") ? Object.keys(condition.properties) : [];
+        const value = key === undefined ? undefined : condition.properties[key];
+        // Without required: [key], an absent key satisfies `if`.
+        if (key === undefined || !exactly(condition.properties, key) || !exactly(value, "const") || !(["string", "boolean"].includes(typeof value.const) || Number.isFinite(value.const) || value.const === null) || q(condition.required) !== q([key]) || !declared([key]))
+            return `if is supported only as exactly { properties: { <field>: { const: <string, finite number, boolean or null> } }, required: [<field>] }, so an absent field does not satisfy it; ${shapes}.`;
+        if (then === undefined && otherwise === undefined || [then, otherwise].some(branch => branch !== undefined && !(exactly(branch, "required") && declared(branch.required))))
+            return `then and else are supported only as exactly { required: [declared properties] } after an if; ${shapes}.`;
+        const met = `${has(key)} && object[${q(key)}] === ${q(value.const)}`;
+        for (const name of then?.required ?? [])
+            found.push({ when: `${met} && !${has(name)}`, key: name, message: `'${name}' is required when '${key}' is ${q(value.const)}.` });
+        for (const name of otherwise?.required ?? [])
+            found.push({ when: `!(${met}) && !${has(name)}`, key: name, message: `'${name}' is required unless '${key}' is ${q(value.const)}.` });
+    }
+    return found;
+}
+/** Whether an input schema accepts `{}`: a list View is read with no input, so web indexes need this. */
+export function acceptsEmpty(input) {
+    if (input === undefined)
+        return true;
+    // Validation applies a root `$ref`'s target too, so each schema along the chain must accept `{}`; an unresolved or cyclic chain does not.
+    // dependentRequired needs a present key; an if needs its field, so `{}` meets only an else. An enum or const must admit `{}`.
+    return rootRefChain(input)?.every(schema => !schema.required?.length && schema.anyOf === undefined && !schema.else?.required?.length
+        && (schema.enum === undefined || schema.enum.some(option => equal({}, option))) && (schema.const === undefined || equal({}, schema.const)) && (schema.type === undefined || [schema.type].flat().includes("object"))) ?? false;
+}
+/**
+ * An input schema as an AI tool catalogue advertises it: some model APIs refuse rules (a root `anyOf`, `if`), so each rule leaves
+ * the schema and becomes a sentence of the description.
+ */
+export function advertised(input, description) {
+    if (!input)
+        return { inputSchema: input, description };
+    const sentences = [], copy = JSON.parse(q(input));
+    const strip = (node, at) => {
+        if (!node || typeof node !== "object")
+            return;
+        const schema = node;
+        // An MCP View tool keeps each rule set of its root `$ref` chain as an `allOf` branch over the merged properties.
+        const branches = Array.isArray(schema.allOf) ? schema.allOf : [];
+        for (const branch of [schema, ...branches.map(branch => ({ ...branch, properties: schema.properties }))]) {
+            const found = rules(branch);
+            if (typeof found !== "string")
+                for (const rule of found)
+                    sentences.push(at ? `In '${at}': ${rule.message}` : rule.message);
+        }
+        if (branches.length && branches.every(branch => Object.keys(branch).every(key => INPUT_RULE_KEYWORDS.includes(key))))
+            delete schema.allOf;
+        for (const keyword of INPUT_RULE_KEYWORDS)
+            delete schema[keyword];
+        for (const [key, child] of Object.entries((schema.properties ?? {})))
+            strip(child, `${at}/${key}`);
+        for (const [key, child] of Object.entries((schema.$defs ?? {})))
+            strip(child, `#/$defs/${key}`);
+        strip(schema.items, `${at}/*`);
+        strip(schema.additionalProperties, `${at}/*`);
+    };
+    strip(copy, "");
+    if (!sentences.length)
+        return { inputSchema: input, description };
+    const text = sentences.join(" ");
+    return { inputSchema: copy, description: typeof description === "string" ? `${description} ${text}` : Object.fromEntries(Object.entries(description).map(([locale, value]) => [locale, `${value} ${text}`])) };
+}
+const bounds = [
+    ["string", "[...value].length", { minLength: "<", maxLength: ">" }],
+    ["number", "value", { minimum: "<", maximum: ">", exclusiveMinimum: "<=", exclusiveMaximum: ">=" }],
+    ["array", "value.length", { minItems: "<", maxItems: ">" }],
+];
+const condition = (type) => ({ null: "value === null", array: "Array.isArray(value)", object: 'typeof value === "object" && value !== null && !Array.isArray(value)', integer: 'typeof value === "number" && Number.isSafeInteger(value)', number: 'typeof value === "number" && Number.isFinite(value)' })[type] ?? `typeof value === ${q(type)}`;
+const typeCheck = (types) => `if (!(${types.map(type => `(${condition(type)})`).join(" || ")})) fail(path, ${q(`Expected ${types.join(" or ")}.`)});`;
+export function emitValidation(plan, refuse = (path, message) => { throw Error(`${path}: ${message}`); }) {
+    const files = {};
+    for (const [kind, operations] of [["views", plan.views], ["procedures", plan.procedures]])
+        for (const [name, operation] of Object.entries(operations)) {
+            const root = operation.input ?? { type: "object", additionalProperties: false };
+            const base = `${kind}/${name}/input`, file = `validation/${kind}/${encodeURIComponent(name)}.ts`;
+            const json = q(root);
+            if (kind === "procedures" && json === q(publishingInput)) {
+                files[file] = `import { transition } from "@aotter/mantle/validation";\nexport const validate = (raw: unknown) => transition(${q(base)}, raw);\n`;
+                continue;
+            }
+            // Only a local `$ref`, or more than 100 nested objects and arrays, can reach the nesting limit: only then is `depth` passed.
+            const recursive = json.includes('"$ref"') || json.split(/[[{]/).length > 101, depth = recursive ? ",depth+1" : "";
+            // Identical bodies share one function.
+            const nodes = new Map(), bodies = new Map(), functions = [], formats = new Set(), patterns = new Map();
+            let equality = false;
+            const resolve = (ref) => {
+                const found = lookup(root, ref);
+                if (!found)
+                    refuse(base, "Input ref must be a valid local JSON pointer.");
+                return found ?? {};
+            };
+            const emit = (schema) => {
+                if (nodes.has(schema))
+                    return nodes.get(schema);
+                const named = `check${nodes.size}`;
+                nodes.set(schema, named);
+                for (const key of Object.keys(schema))
+                    if (!supported.has(key))
+                        refuse(base, `Generated input validation does not support '${key}'.`);
+                const lines = recursive ? ['if (depth > 100) fail(path, "Input nesting exceeds 100 levels.");'] : [];
+                const check = (invalid, message) => lines.push(`if (${invalid}) fail(path, ${q(message)});`);
+                if (schema.nullable)
+                    lines.push("if (value === null) return;");
+                if (schema.$ref !== undefined)
+                    lines.push(`${emit(resolve(schema.$ref))}(value,path${depth});`);
+                const types = [schema.type].flat().filter((type) => !!type);
+                for (const type of types)
+                    if (!"null array object integer number string boolean".split(" ").includes(type))
+                        refuse(base, `Unsupported input type '${type}'.`);
+                if (types.length)
+                    lines.push(typeCheck(types));
+                // After a single type check `fail` (never) has narrowed `value`: that type's guard is implied.
+                const only = types.length === 1 ? types[0] : undefined;
+                const guard = (type, test = `(${condition(type)})`) => only === type || type === "number" && only === "integer" ? "" : test + " && ";
+                if (schema.enum) {
+                    if (!finite(schema.enum))
+                        refuse(base, "Input enum numbers must be finite; JSON has no Infinity or NaN.");
+                    equality = true;
+                    check(`!${literal(schema.enum)}.some(option=>equal(value,option))`, "Value is not in enum.");
+                }
+                if (schema.const !== undefined) {
+                    if (!finite(schema.const))
+                        refuse(base, "Input const numbers must be finite; JSON has no Infinity or NaN.");
+                    equality = true;
+                    check(`!equal(value,${literal(schema.const)})`, "Value violates const.");
+                }
+                for (const [type, measure, keywords] of bounds)
+                    for (const [key, operator] of Object.entries(keywords))
+                        if (schema[key] !== undefined)
+                            check(`${guard(type)}${measure} ${operator} ${schema[key]}`, `Value violates ${key}.`);
+                if (schema.multipleOf !== undefined)
+                    check(`${guard("number", 'typeof value === "number"')}!(Math.abs(value / ${schema.multipleOf} - Math.round(value / ${schema.multipleOf})) < 1e-9)`, "Number violates multipleOf.");
+                if (schema.pattern !== undefined) {
+                    try {
+                        new RegExp(schema.pattern);
+                    }
+                    catch {
+                        refuse(base, "Input pattern is not a valid regular expression.");
+                    }
+                    if (!patterns.has(schema.pattern))
+                        patterns.set(schema.pattern, `pattern${patterns.size}`);
+                    check(`${guard("string", 'typeof value === "string"')}!${patterns.get(schema.pattern)}.test(value)`, "String does not match pattern.");
+                }
+                if (schema.format) {
+                    if (schema.format === "email")
+                        check(`${guard("string", 'typeof value === "string"')}!/^[^\\s@]+@[^\\s@]+$/u.test(value)`, "Expected an email with one @, non-empty local and domain parts, and no whitespace.");
+                    else if (schema.format === "uri")
+                        lines.push(`${only === "string" ? "" : 'if (typeof value === "string") '}{ let url: URL | undefined; try { url = new URL(value); } catch {} if (url?.protocol !== "http:" && url?.protocol !== "https:") fail(path, "Expected an absolute http or https URL."); }`);
+                    else if (!["date", "date-time"].includes(schema.format))
+                        refuse(base, `Generated input validation does not support format '${schema.format}'; ${shapes} for the supported formats.`);
+                    else {
+                        const scalar = schema.format === "date" ? "encodeDate" : "encodeTimestamptz";
+                        formats.add(scalar);
+                        lines.push(`${only === "string" ? "" : 'if (typeof value === "string") '}try { ${scalar}(value); } catch { fail(path, ${q(`Expected a valid ${schema.format}.`)}); }`);
+                    }
+                }
+                if (schema.items)
+                    lines.push(`${only === "array" ? "" : "if (Array.isArray(value)) "}for (let i=0;i<value.length;i++) ${emit(schema.items)}(value[i],path+"/"+i${depth});`);
+                // Several keys that need no JSON-pointer escaping are checked by one loop, in the same order.
+                const required = schema.required ?? [], checks = Object.entries(schema.properties ?? {}).map(([key, child]) => [key, emit(child)]);
+                const loop = (keys) => keys.length > 1 && keys.every(key => pointer(key) === key);
+                const object = loop(required) ? [`for (const key of ${q(required)}) if (!Object.hasOwn(object,key)) fail(path+"/"+key,"Required field is missing.");`] : required.map(key => `if (!Object.hasOwn(object,${q(key)})) fail(path+${q("/" + pointer(key))},"Required field is missing.");`);
+                if (loop(checks.map(([key]) => key)))
+                    object.push(`for (const [key,check] of [${checks.map(([key, fn]) => `[${q(key)},${fn}]`)}] as const) if (Object.hasOwn(object,key)) check(object[key],path+"/"+key${depth});`);
+                else
+                    for (const [key, fn] of checks)
+                        object.push(`if (Object.hasOwn(object,${q(key)})) ${fn}(object[${q(key)}],path+${q("/" + pointer(key))}${depth});`);
+                if (schema.additionalProperties === false || typeof schema.additionalProperties === "object")
+                    object.push(`for (const key of Object.keys(object)) if (!(${q(Object.keys(schema.properties ?? {}))} as readonly string[]).includes(key)) { const childPath = path+"/"+key.replace(/~/g,"~0").replace(/\\//g,"~1"); ${schema.additionalProperties === false ? 'fail(childPath,"Unknown field.");' : `${emit(schema.additionalProperties)}(object[key],childPath${depth});`} }`);
+                const checked = rules(schema);
+                if (typeof checked === "string")
+                    refuse(base, checked);
+                else
+                    for (const rule of checked)
+                        object.push(`if (${rule.when}) fail(path${rule.key === undefined ? "" : `+${q("/" + pointer(rule.key))}`}, ${q(rule.message)});`);
+                if (object.length)
+                    lines.push(`${only === "object" ? "" : `if (${condition("object")}) `}{ const object = value as Record<string,unknown>;\n${object.join("\n")}\n}`);
+                const body = lines.join("\n");
+                // Without recursion nothing calls a check before its body is complete, so an identical body's function serves it.
+                const fn = recursive ? named : bodies.get(body) ?? named;
+                if (fn === named) {
+                    bodies.set(body, fn);
+                    functions.push(`function ${fn}(value:unknown,path:string${recursive ? ",depth:number" : ""}):void {\n${body}\n}`);
+                }
+                nodes.set(schema, fn);
+                return fn;
+            };
+            const validate = emit(root);
+            const fields = kind === "views" ? Object.entries(root.properties ?? {}).map(([key, schema]) => {
+                const type = [schema.type].flat().find(type => type && type !== "null");
+                return type === "boolean" || type === "integer" || type === "number" ? [key, type] : [key];
+            }) : undefined;
+            const helpers = [...(functions.length ? ["fail"] : []), ...(equality ? ["equal"] : []), ...(fields ? ["query as read"] : [])];
+            const code = `${helpers.length ? `import { ${helpers.join(", ")} } from "@aotter/mantle/validation";\n` : ""}${formats.size ? `import { ${[...formats].join(", ")} } from "@aotter/mantle/scalars";\n` : ""}${[...patterns].map(([pattern, name]) => `const ${name} = new RegExp(${q(pattern)});\n`).join("")}${functions.join("\n")}
+export function validate(raw:unknown):Record<string,unknown> { ${validate}(raw,${q(base)}${recursive ? ",0" : ""}); return raw as Record<string,unknown>; }
+${fields ? `export const query = (params:URLSearchParams) => read(params, validate, ${q(`${kind}/${name}`)}, ${q(fields)});\n` : ""}`;
+            files[file] = code;
+        }
+    return files;
+}

package/dist/usecase/web.js

@@ -0,0 +1,23 @@
+import { databaseImport, q } from "../domain/entry.js";
+import { authLines, conversions } from "../domain/input.js";
+import { acceptsEmpty } from "./validation.js";
+export function emitWeb(plan, lowered, target) {
+    const views = Object.entries(plan.views).filter(([, v]) => v.surface === "public");
+    const table = views.map(([name, v], i) => {
+        const binds = lowered.views[name]?.public?.binds ?? [], convert = conversions(v.input?.properties, binds, target);
+        const booleans = Object.keys(v.input?.properties ?? {}).filter(field => binds.some(b => b.k === "input" && String(b.name).toLowerCase() === field.toLowerCase() && String(b.type) === "bool"));
+        const check = authLines(v.requires, `views/${name}`, binds, !target.endsWith("postgres"));
+        return `[${q(name)}, { ${check.length ? `check: (caller) => {${check.join("")}}, ` : ""}${acceptsEmpty(v.input) ? "" : "unlisted: true, "}query: input${i}, page: async (db, caller, input, paging) => (await import("./paged/views/${encodeURIComponent(name)}.js")).default(db, caller, input, paging)${convert ? `, convert: ${convert}` : ""}${booleans.length ? `, booleans: ${q(booleans)}` : ""} }]`;
+    });
+    return { "web.ts": [
+            ...(plan.access ? ['import { userBinds } from "@aotter/mantle/user-fields";'] : []),
+            ...([...Object.values(plan.views)].some(v => v.requires?.auth?.all.length) ? ['import { deny, isAdmin, isUser } from "@aotter/mantle/contracts";'] : []),
+            ...views.flatMap(([n], i) => [`import { query as input${i} } from "./validation/views/${encodeURIComponent(n)}.js";`, `import type { Row as Row${i} } from "./views/${encodeURIComponent(n)}.js";`]),
+            'import { web as site, type Options, type Page } from "@aotter/mantle/web";',
+            databaseImport(target),
+            `type App = { Rows: {${views.map(([n], i) => `${q(n)}:Row${i}`).join(";")}}; Inputs: {${views.map(([n, v]) => `${q(n)}:${Object.keys(v.input?.properties ?? {}).map(k => q(k)).join(" | ") || "never"}`).join(";")}}; List: ${views.filter(([, v]) => acceptsEmpty(v.input)).map(([n]) => q(n)).join(" | ") || "never"} };`,
+            "export function web<const P extends Record<string, Page<App>>, E = unknown>(options: Options<App, Database, P, E>) {",
+            `  return site<Database, E>(${plan.access ? `{...options, fields: ${q(plan.access.userFields)}, accessTargets: () => import("./access-targets.js").then(m => m.targets)}` : '{...options, accessTargets: () => import("./access-targets.js").then(m => m.targets)}'}, [${table.join(", ")}]);`,
+            "}"
+        ].join("\n") + "\n" };
+}

package/docs/examples/README.md

@@ -1,20 +1,35 @@
-# Examples hub
+# Examples
 
-Every page is a whole service in the 0.2.0 grammar: its manifests compile with
-`mantle generate` (the SDK repository compiles each one in its checks). Copy the shape you need into
-your project's `manifests/`; none is a template to copy wholesale.
+Start from the **app shell**, then copy the example closest to your app on top of it. Each example shows a few
+capabilities the others do not; combine them for anything else.
 
-| Example | What it shows | Handler code |
-|---|---|---|
-| [`reference-service/`](./reference-service/README.md) | A runnable service with its smoke test: scoped orders, SQL Views and Procedures, hooks, a cron, REST, both MCP surfaces, Admin's API and console email-OTP sign-in. The release gate runs it. | yes |
-| [Intake form](./intake.md) | An anonymous form: one SQL `INSERT` and a staff View. | none |
-| [Intake with bot check and notification](./intake-hooks.md) | A Turnstile check as the Procedure's guard, an email from an after hook. | 2 handlers |
-| [Reservation requests](./reservation.md) | A request queue with a Schema `check`. | none |
-| [Publication](./publication.md) | Localized posts with a parent identity, per-locale lists and `mantle.search`. | none |
-| [Legal documents and consent](./legal-documents.md) | Immutable revisions, and an acceptance written only for a published revision. | none |
-| [Procurement approvals](./procurement.md) | Members see their own rows through `auth.uid()`; staff review with an optimistic lock. | none |
-| [Commerce catalog and orders](./commerce.md) | A published catalog, guest orders and a locked staff review. | none |
-| [Commerce inventory](./commerce-inventory.md) | Server-side pricing, atomic stock reservation with `checks` and locks, a scheduled expiry and a verified payment callback. | 3 handlers |
-| [Guarded API access](./guarded-api.md) | API keys through a custom `CallerResolver`, scopes and a live entitlement guard. | 2 handlers |
+| Example | Shows |
+|---|---|
+| [App shell](./app-shell/README.md) | Better Auth (email OTP, `admin` + `user`), one Worker fetch, Admin, MCP, REST, local acceptance kit. No business manifests. |
+| [Recipes](./recipes/README.md) | Publishing (draft → publish), translations, visitor pages with SEO, JSON-LD, `llms.txt`, Markdown and hreflang alternates, R2 media. |
+| [Club events](./club-events/README.md) | Members who see and change only their own rows, no duplicates, capacity that never oversells, a handler that checks before writing, a member MCP tool, members-only sign-up. |
+| [Purchasing](./purchasing/README.md) | An internal workflow: guarded status transitions, admin-only approval (Admin and admin MCP), optimistic concurrency, several writes in one transaction, an external API with a signed callback, email and cron. |
+| [Generated website](./generated-web/README.md) | The smallest public site: list and detail pages, REST, `llms.txt`, sitemap, Markdown alternates. |
 
+## Combining
+
+| You need | Take |
+|---|---|
+| Stock that never oversells (orders, tickets, bookings) | club-events' capacity: a Schema `checks` constraint plus the decrement in the same program |
+| Employees or customers who see only their own records | club-events' `restrict: { <schema>: "author_id = auth.uid()" }` |
+| An approval step, or any state machine | purchasing's guarded `UPDATE ... WHERE requestStatus = ...` Procedures |
+| A third-party API that answers later (webhooks, callbacks) | purchasing's `src/routes.ts`: verify the raw request, then call a Procedure |
+| Public, multilingual, search- and AI-friendly pages | recipes' `src/routes.ts` |
+| Invite-only or members-only sign-up | club-events' `members` allowlist + `src/signup.ts` |
+| Notifications and reminders | purchasing's `EmailSender` call and `src/schedule.ts` |
+
+When you copy an example only for one of its patterns, delete what your app does not need. Copying club-events, for
+example, also brings its `members` allowlist and `src/signup.ts` (members-only sign-up); remove both, or restore the
+shell's allow-all `src/signup.ts`, unless sign-up should be invite-only. Purchasing brings its supplier callback
+(`src/routes.ts`, `src/supplier.ts`), email (`src/notify.ts`), cron (`src/schedule.ts` and `triggers.crons`) and its
+`wrangler.jsonc` secrets. `pnpm generate` and `tsc` point at leftovers that reference removed Schemas.
+
+Every example uses two roles: `admin` (the admin layer) and `user`.
+
+[Reference service](https://github.com/aotter/mantle/tree/v0.2.0-alpha.8/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
 Projects on 0.1.x move with [the upgrade guide](../upgrade-0.1-to-0.2.md).

package/docs/examples/app-shell/README.md

@@ -0,0 +1,86 @@
+# App shell
+
+The wiring every Mantle Cloudflare app needs, ready to copy: Better Auth (email OTP, admin + user roles),
+one Worker fetch (auth routes → your routes → Admin → MCP → generated REST), the Admin console assets, and a
+local acceptance kit. It has no business manifests: add your own, or copy one of the examples on top of it.
+
+## Start an app
+
+```sh
+cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/   # or from this repository
+cp -R node_modules/@aotter/mantle/docs/examples/club-events/. my-app/ # optional: an example on top
+cd my-app
+# package.json: pin the exact installed Mantle version for @aotter/mantle, -admin and -ui
+pnpm install
+pnpm generate          # writes generated/ and lists any `handler: { ref }` to implement in src/handlers.ts
+pnpm types && pnpm check
+cp .dev.vars.example .dev.vars
+pnpm db:init && pnpm db:seed   # db:seed only when the example has seed.sql
+pnpm dev                       # one-time codes print to this log
+pnpm smoke                     # when the copied example has smoke.mjs
+```
+
+npm works too (`npm install`, `npm run …`). `package.json` pins `@better-auth/core` and `@better-auth/utils` even though
+the shell does not import them: they are the exact versions the SDK's Better Auth peers require, and without them a fresh
+install resolves newer ones (npm ERESOLVE, or a second Better Auth type tree under pnpm). Keep every Better Auth package
+on one version.
+
+## Files you edit
+
+| File | What it is for |
+|---|---|
+| `manifests/*.yaml` | Your Schemas, Views, Procedures and Triggers. `pnpm generate` compiles every file here. |
+| `src/handlers.ts` | Code for each `handler: { ref }` Procedure. The Store it receives is bound to the same caller. |
+| `src/routes.ts` | App-owned routes: visitor pages, SEO files, webhooks and callbacks. |
+| `src/admin.tsx` | Optional, not shipped: the Admin entry (`defineAdmin(admin, { nav, pages, home, components, plugins, mcp })`) `mantle bundle` builds instead of the built-in one. Add it to group the sidebar or replace Admin regions; see docs/handbook/guides/native-admin.md. |
+| `src/sign-in.ts` | Member sign-in page at `/sign-in` (email code, then back to `?return=`) and `signInRedirect(request)` for pages that need a signed-in visitor. Unstyled; delete it if the app has no member pages. |
+| `src/schedule.ts` | Cron work. Add the cron to `wrangler.jsonc` `triggers.crons`. |
+| `src/signup.ts` | `allowSignUp(env, email)`: who may create an account (allow-all by default). `auth.ts` calls it before Better Auth creates a user; `ADMIN_EMAIL` is always allowed. |
+| `src/auth.ts` | Better Auth options. Two roles only: `admin` (the admin layer) and `user`. Replace the console OTP sender before deploying. |
+| `smoke.mjs` | Your acceptance steps on `smoke-kit.mjs` (fresh local D1, OTP sign-in per user, REST/MCP/Admin calls). |
+
+`src/service.ts` and `src/index.ts` rarely change. Delete the blocks marked `MCP / OAuth (optional)` in `auth.ts`
+and `service.ts` if the app has no MCP.
+
+Search for `AGENT:` to find what an app must fill in.
+
+## Local testing notes
+
+- Better Auth allows 3 OTP requests per minute per client IP. `smoke-kit.mjs` gives each user its own
+  `cf-connecting-ip`; when testing by hand, wait a minute or vary that header.
+- `ADMIN_EMAIL`'s first verified sign-in becomes `admin` while no admin exists. The sign-in response may still show
+  the previous role; `/admin/api/me` shows the current one.
+- Admin HTTP routes are listed in `docs/handbook/guides/native-admin.md`.
+
+### MCP acceptance
+
+Generation declares tools; the app owns whether and where a remote endpoint is mounted.
+In your `smoke.mjs`, reuse the generated static tool names rather than maintaining a second list:
+
+```js
+import assert from "node:assert/strict";
+import { assertMcpDiscovery, smoke } from "./smoke-kit.mjs";
+import { developerConsole } from "./generated/admin-descriptors.ts";
+
+await smoke(async ({ origin, owner, signIn, mcp }) => {
+  const cookie = await signIn(owner);
+  const tools = developerConsole.interfaces.callable.filter(tool => tool.surface === "admin");
+  await assertMcpDiscovery(`${origin}/mcp/admin`, { tools, headers: { cookie, origin } });
+  // Denial is a separate assertion, not successful discovery.
+  assert.equal((await mcp("/mcp/admin")).status, 401);
+});
+```
+
+Node 22.22+ can read this pure static
+TypeScript descriptor directly; no generated request handlers are executed to derive expected names.
+A TypeScript smoke scenario can instead import `tools` from generated `mcp.ts`.
+Explicitly select the permitted subset if the app narrows authorization, and include any app-composed tools.
+The assertion initializes MCP, forwards supplied identity/session headers, reads all tools/list pages,
+and compares exact names without calling business tools. JSON/SSE protocol failures, missing routes,
+unexpected/missing tools and repeated/excessive pagination fail; it never obtains credentials or mounts routes.
+
+This local cookie test does not prove OAuth Bearer or an external client's connection. Test those separately
+with supplied credentials and record their results. For each declared interface, the existing handoff/README/test
+report must say verified (command, identity and result), intentionally not exposed, or deferred/unverified with a
+reason. WebMCP-only applications remain valid; an interrupted preview must retain the remote acceptance item
+as deferred rather than silently claiming completion.

package/docs/examples/app-shell/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "mantle-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "generate": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin",
+    "types": "wrangler types --include-runtime=false",
+    "db:init": "wrangler d1 execute mantle-app --local --file generated/schema.sql",
+    "db:seed": "wrangler d1 execute mantle-app --local --file seed.sql",
+    "build": "mantle bundle src/index.ts dist",
+    "test": "node --test generated/admin-mcp-app.check.mjs",
+    "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
+    "check": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin --check && wrangler types --include-runtime=false --check && tsc --noEmit",
+    "smoke": "node smoke.mjs"
+  },
+  "dependencies": {
+    "@aotter/mantle": "0.2.0-alpha.8",
+    "@aotter/mantle-ui": "0.2.0-alpha.8",
+    "@better-auth/cimd": "1.7.7",
+    "@better-auth/core": "1.7.7",
+    "@better-auth/mcp": "1.7.7",
+    "@better-auth/oauth-provider": "1.7.7",
+    "@better-auth/utils": "0.4.2",
+    "@modelcontextprotocol/ext-apps": "2.0.0",
+    "@modelcontextprotocol/server": "2.2.0",
+    "better-auth": "1.7.7",
+    "@aotter/mantle-admin": "0.2.0-alpha.8",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "5.20260904.1",
+    "@types/node": "^26",
+    "@types/react": "^19.3.0",
+    "playwright-core": "1.62.1",
+    "typescript": "^6.0.3",
+    "wrangler": "4.129.0"
+  },
+  "engines": {
+    "node": ">=22.22"
+  }
+}

package/docs/examples/app-shell/pnpm-workspace.yaml

@@ -0,0 +1,8 @@
+# pnpm 10+ blocks dependency build scripts by default; wrangler needs these two. `packages` keeps pnpm 9 happy.
+packages: ["."]
+allowBuilds:
+  esbuild: true
+  workerd: true
+onlyBuiltDependencies:
+  - esbuild
+  - workerd

package/docs/examples/app-shell/smoke-kit.mjs

@@ -0,0 +1,154 @@
+// Local acceptance kit: runs the app under `wrangler dev --local` on a fresh D1 and drives it over HTTP like a browser or agent.
+// Usage in smoke.mjs:
+//   import { smoke } from "./smoke-kit.mjs";
+//   await smoke(async ({ call, mcp, signIn, owner, step }) => { const admin = await signIn(owner); ... step("..."); });
+//   Extra Worker variables: await smoke(scenario, { vars: { SUPPLIER_API_URL: "http://127.0.0.1:9999" } });
+import assert from "node:assert/strict";
+import { execFile, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+/** Read-only remote acceptance. Pass generated tools filtered for this surface and the supplied test identity. */
+export async function assertMcpDiscovery(endpoint, { tools, headers = {} }) {
+  const expected = tools.map(tool => tool.name).sort();
+  assert.equal(new Set(expected).size, expected.length, "expected tools contain duplicate names");
+  const requestHeaders = new Headers(headers);
+  requestHeaders.set("content-type", "application/json");
+  requestHeaders.set("accept", "application/json, text/event-stream");
+  let id = 0;
+  const rpc = async (method, params, notification = false) => {
+    const message = { jsonrpc: "2.0", ...(notification ? {} : { id: ++id }), method, ...(params === undefined ? {} : { params }) };
+    const response = await fetch(endpoint, { method: "POST", headers: requestHeaders, redirect: "error", signal: AbortSignal.timeout(10_000), body: JSON.stringify(message) });
+    assert.equal(response.status, notification ? 202 : 200, `MCP ${method}: HTTP ${response.status}`);
+    if (notification) { await response.body?.cancel(); return; }
+    const text = await response.text(), type = response.headers.get("content-type") ?? "";
+    let replies;
+    if (type.includes("text/event-stream")) {
+      replies = text.replace(/\r\n/g, "\n").split("\n\n").map(event => event.split("\n").filter(line => line.startsWith("data:")).map(line => line.slice(5).trimStart()).join("\n")).filter(Boolean).map(data => JSON.parse(data));
+    } else {
+      assert.ok(type.includes("application/json"), `MCP ${method}: expected JSON or SSE`);
+      replies = [JSON.parse(text)];
+    }
+    const matches = replies.filter(reply => reply?.id === message.id);
+    assert.equal(matches.length, 1, `MCP ${method}: expected one response with the request id`);
+    const reply = matches[0];
+    assert.equal(reply.jsonrpc, "2.0", `MCP ${method}: invalid JSON-RPC version`);
+    assert.ok(!Object.hasOwn(reply, "error"), `MCP ${method}: returned a JSON-RPC error`);
+    assert.ok(reply.result && typeof reply.result === "object" && !Array.isArray(reply.result), `MCP ${method}: missing result object`);
+    const session = response.headers.get("mcp-session-id");
+    if (session) requestHeaders.set("mcp-session-id", session);
+    return reply.result;
+  };
+  const initialized = await rpc("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "mantle-smoke", version: "1" } });
+  assert.equal(initialized.protocolVersion, "2025-11-25", "MCP initialize: unsupported protocol version");
+  assert.ok(initialized.capabilities?.tools && typeof initialized.capabilities.tools === "object" && !Array.isArray(initialized.capabilities.tools), "MCP initialize: no tools capability");
+  assert.ok(typeof initialized.serverInfo?.name === "string" && typeof initialized.serverInfo?.version === "string", "MCP initialize: invalid serverInfo");
+  requestHeaders.set("mcp-protocol-version", initialized.protocolVersion);
+  await rpc("notifications/initialized", undefined, true);
+  const names = [], cursors = new Set();
+  let cursor;
+  do {
+    assert.ok(cursors.size < 100, "MCP tools/list: exceeded 100 pages");
+    const page = await rpc("tools/list", cursor === undefined ? {} : { cursor });
+    assert.ok(Array.isArray(page.tools) && page.tools.every(tool => tool && typeof tool.name === "string" && tool.name.length > 0 && tool.inputSchema && typeof tool.inputSchema === "object" && !Array.isArray(tool.inputSchema) && tool.inputSchema.type === "object"), "MCP tools/list: invalid tools");
+    names.push(...page.tools.map(tool => tool.name));
+    cursor = page.nextCursor;
+    if (cursor !== undefined) {
+      assert.ok(typeof cursor === "string" && cursor.length > 0 && !cursors.has(cursor), "MCP tools/list: invalid or repeated cursor");
+      cursors.add(cursor);
+    }
+  } while (cursor !== undefined);
+  assert.deepEqual(names.sort(), expected, "MCP tools/list: discovered tools differ from the expected permitted tools");
+  return names;
+}
+
+const database = "mantle-app"; // wrangler.jsonc d1_databases[0].database_name
+const env = { ...process.env, WRANGLER_SEND_METRICS: "false" };
+
+export async function smoke(scenario, { vars = {} } = {}) {
+  const port = 18000 + Math.floor(Math.random() * 1000), origin = `http://127.0.0.1:${port}`, owner = "owner@example.test";
+  const state = mkdtempSync(join(tmpdir(), "mantle-smoke-"));
+  // Deployment DDL is explicit: nothing at runtime creates tables.
+  for (const file of ["generated/schema.sql", ...(existsSync("seed.sql") ? ["seed.sql"] : [])]) {
+    const applied = spawnSync("pnpm", ["exec", "wrangler", "d1", "execute", database, "--local", "--persist-to", state, "--file", file], { encoding: "utf8", env });
+    assert.equal(applied.status, 0, applied.stdout + applied.stderr);
+  }
+  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:local-smoke-secret-0123456789abcdef", ...Object.entries(vars).flatMap(([name, value]) => ["--var", `${name}:${value}`])],
+  // its own process group: pnpm does not pass a signal on to wrangler and workerd
+  { env: { ...env, CI: "1" }, stdio: ["ignore", "pipe", "pipe"], detached: true });
+  let logs = "";
+  wrangler.stdout.on("data", chunk => { logs += chunk; });
+  wrangler.stderr.on("data", chunk => { logs += chunk; });
+
+  // Better Auth limits OTP requests to 3 per minute per IP: each signed-in user gets its own client IP.
+  const ips = new Map();
+  const ipOf = email => ips.get(email) ?? (ips.set(email, `203.0.113.${ips.size + 1}`), ips.get(email));
+  /** method, path, { cookie, body, ip, headers } -> { status, body, headers } */
+  const call = async (method, path, { cookie, body, ip, headers = {} } = {}) => {
+    const response = await fetch(`${origin}${path}`, { method, headers: { "content-type": "application/json", origin, ...(cookie ? { cookie } : {}), ...(ip ? { "cf-connecting-ip": ip } : {}), ...headers },
+      ...(body === undefined ? {} : { body: typeof body === "string" ? body : JSON.stringify(body) }) });
+    const text = await response.text();
+    let parsed; try { parsed = text ? JSON.parse(text) : null; } catch { parsed = text; }
+    return { status: response.status, body: parsed, headers: response.headers };
+  };
+  /** MCP tools/list (no name) or tools/call on /mcp or /mcp/admin. */
+  const mcp = async (path, cookie, name, args) => {
+    const response = await fetch(`${origin}${path}`, { method: "POST", headers: { "content-type": "application/json", origin, 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(), 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: request a code, read it from the wrangler log, sign in; returns the cookie header. */
+  const signIn = async email => {
+    const before = logs.length, ip = ipOf(email);
+    assert.equal((await call("POST", "/api/auth/email-otp/send-verification-otp", { body: { email, type: "sign-in" }, ip })).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 }, ip });
+    assert.equal(signed.status, 200, JSON.stringify(signed.body));
+    return signed.headers.getSetCookie().map(c => c.split(";")[0]).join("; ");
+  };
+  /** Run SQL against the local D1 (inspect state or inject a failure). Async, so the server's sockets stay serviced. */
+  const sql = async command => {
+    const { stdout } = await promisify(execFile)("pnpm", ["exec", "wrangler", "d1", "execute", database, "--local", "--persist-to", state, "--command", command, "--json"], { encoding: "utf8", env });
+    return JSON.parse(stdout)[0].results;
+  };
+  /** Fire the Worker's scheduled() handler (wrangler dev --test-scheduled). */
+  const cron = async expression => (await fetch(`${origin}/cdn-cgi/local/scheduled?cron=${encodeURIComponent(expression)}`)).status;
+  /** Wait until the wrangler log (console.log from the Worker, e.g. ConsoleEmailSender) matches. */
+  const waitForLog = async pattern => {
+    for (let i = 0; i < 40; i++) { if (pattern.test(logs)) return; await new Promise(resolve => setTimeout(resolve, 100)); }
+    assert.fail(`no log line matching ${pattern}`);
+  };
+  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 { await fetch(`${origin}/api/auth/ok`); break; } catch { /* starting */ }
+      if (attempt > 240) throw new Error("the Worker did not start");
+      await new Promise(resolve => setTimeout(resolve, 250));
+    }
+    await scenario({ origin, owner, call, mcp, signIn, sql, cron, waitForLog, step, logs: () => logs });
+    console.log("smoke 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 });
+  }
+}