@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.10

package/dist/usecase/validation.js

@@ -0,0 +1,241 @@
+/** 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 key of ["minLength", "maxLength", "minItems", "maxItems"])
+                    if (schema[key] !== undefined && (!Number.isSafeInteger(schema[key]) || schema[key] < 0))
+                        refuse(base, `${key} must be a non-negative safe integer.`);
+                for (const key of ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"])
+                    if (schema[key] !== undefined && (typeof schema[key] !== "number" || !Number.isFinite(schema[key])))
+                        refuse(base, `${key} must be a finite number.`);
+                if (schema.multipleOf !== undefined && (typeof schema.multipleOf !== "number" || !Number.isFinite(schema.multipleOf) || schema.multipleOf <= 0))
+                    refuse(base, "multipleOf must be a positive finite number.");
+                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,43 @@
-# 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 an app with `mantle init`, which writes the **app shell** once. The examples are references: each shows a few
+capabilities the others do not. Find each need in **Combining** below, read that example's manifest and source, and
+take the pattern into your own manifests and `src/`. Do not copy an example directory over your app.
 
-| 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 |
+| An order, cart or import with several rows that must all commit or none | one SQL Procedure over `json_each(input.items)` with a counted check that refuses unknown lines (`mantle help typed-queries`, "Several rows that commit together") |
+| 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 |
+| Approve first, then reserve or spend | purchasing's `approve-request-write`: the guarded status change and the budget deduction in one program (`mantle help sql-patterns`, "Approve before reserving") |
+| A status chosen while writing (auto-approve small requests) | purchasing's `submit-request`: `CASE` in the INSERT ("Choose a status while writing: CASE") |
+| Edit only the fields given | `COALESCE(input.field, field)` ("Change only the fields given") |
+| Create or add (restock, counters) | `INSERT ... ON CONFLICT (...) DO UPDATE` ("Create or add") |
+| Refuse while something still refers to it | a `NOT EXISTS` guard in the UPDATE (purchasing's `submit-request` ledger row; "Refuse while something refers to it") |
+| A record with its children in one read | club-events' `event-roster`: a JSON array per row ("A row with its children in one read") |
+| The latest row per group, rankings | `row_number() OVER (PARTITION BY ...)` ("The latest row of each group") |
+| 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` |
+
+If you do copy an example's files, 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.10/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,121 @@
+# 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, taking patterns from the examples (`mantle help examples`).
+
+## Start an app
+
+```sh
+npx @aotter/mantle@<exact version> init my-app   # writes this shell once, Mantle packages pinned to that version
+cd my-app
+pnpm install
+# add manifests/*.yaml (mantle help four-atoms; patterns: mantle help examples)
+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                   # add seed.sql and run pnpm db:seed for fixtures
+pnpm dev                       # one-time codes print to this log
+pnpm smoke                     # your smoke.mjs on smoke-kit.mjs (see Files you edit)
+pnpm accept                    # hand each role to a fresh evaluator (see Independent acceptance)
+pnpm test                      # Admin MCP App check: needs Chrome (npx playwright-core install chromium, or MANTLE_TEST_CHROMIUM=<executable>)
+```
+
+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). |
+| `accept.mjs` | Independent acceptance setup: one URL per role that carries its session, plus a minimal MCP client. Add a fixtures module for realistic data. |
+
+`src/service.ts` and `src/index.ts` rarely change. The default shell mounts REST and MCP together. If the app deliberately
+chooses asymmetric exposure, delete the blocks marked `MCP / OAuth (deliberate exception)` in `auth.ts` and `service.ts`;
+HTTP-only Procedures will keep generating with a warning.
+
+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.
+- More administrators: in Admin, **More → Administrators** invites by email and **More → Members** grants Admin to an
+  existing member. `docs/handbook/cloudflare/authentication.md` (Identity helpers) has the same operations as an API.
+- Admin HTTP routes are listed in `docs/handbook/guides/native-admin.md`.
+
+`mantle help local-testing` lists what the smoke covers: every Procedure at its edges, each caller's isolation,
+visitor pages without JavaScript, MCP discovery and Admin's MCP App.
+Scripted smoke is not independent acceptance; before reporting a user-facing
+deliverable done, follow the independent acceptance guide: `mantle help agent-workflow-acceptance`.
+
+### Independent acceptance
+
+`pnpm accept` (optionally `pnpm accept --fixtures fixtures.mjs --user member@example.test`; with npm, `npm run accept -- --fixtures …`) starts the app on a fresh local D1,
+signs the admin in, runs your fixtures module, signs the user in and prints one local URL per role:
+
+```text
+visitor (anonymous): http://127.0.0.1:18741
+admin (owner@example.test): http://127.0.0.1:46467  MCP http://127.0.0.1:46467/mcp/admin  Admin http://127.0.0.1:46467/admin
+user (member@example.test): http://127.0.0.1:42607  MCP http://127.0.0.1:42607/mcp
+```
+
+Each URL forwards to the app with that role's session; the evaluator never sees a cookie, and the URL refuses
+`/api/auth/*`, so it cannot sign out, sign in as someone else or mint credentials. Give an evaluator only its role's URL:
+
+- MCP: configure the URL as a streamable HTTP MCP server, or, without an MCP client,
+  `node accept.mjs mcp <url>/mcp` lists the tools and `node accept.mjs mcp <url>/mcp <tool> '<json>'` calls one.
+- Admin and member pages: open the URL in a browser (a person's, or Playwright for an agent); it is already
+  signed in.
+- REST: send requests to the URL with no credential.
+
+The fixtures module's default export receives `{ call, mcp, signIn, sql, sessions, user }` and runs between the two
+sign-ins, so an invite-only app can admit the user first. Create records through the app's own REST/MCP as real
+users (other members' records, several states, more than one page); `sql` is for what no surface may write, and returns storage column names (lower case unless aliased).
+Ctrl-C stops the app and deletes its data. To accept an external MCP host's OAuth connection instead, see the guide.
+
+### 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/accept.mjs

@@ -0,0 +1,91 @@
+// Independent acceptance setup (mantle help agent-workflow-acceptance): hands each role to a fresh evaluator without a credential.
+//   node accept.mjs [--fixtures fixtures.mjs] [--user member@example.test]
+//     Starts the app on a fresh local D1 (schema.sql, then seed.sql), signs the admin in with email OTP, runs the optional
+//     fixtures module (default export async ({ call, mcp, signIn, sql, sessions, user }) => {...}: realistic records through
+//     the app's own REST/MCP as real users, e.g. other members' orders and more than one page), signs the user in, then
+//     serves one local proxy per role that adds that role's session to every request. Give an evaluator only its role's URL
+//     (a visitor gets the app's own origin):
+//     MCP at <proxy>/mcp (user) or <proxy>/mcp/admin (admin), Admin at <proxy>/admin, pages and REST at <proxy>/.
+//     The proxy refuses /api/auth/* so the evaluator cannot sign out, sign in or mint credentials. Ctrl-C stops everything.
+//   node accept.mjs mcp <endpoint> [tool [json-arguments]]
+//     A minimal MCP client for an evaluator without one: lists the tools, or calls one and prints the raw result.
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+if (process.argv[2] === "mcp") await client(process.argv[3], process.argv[4], process.argv[5]).catch(error => { console.error(error.message); process.exitCode = 1; });
+else await setup();
+
+async function setup() {
+  const { values } = parseArgs({ args: process.argv.slice(2).filter(arg => arg !== "--"), options: { fixtures: { type: "string" }, user: { type: "string", default: "member@example.test" } } });
+  const { startApp } = await import("./smoke-kit.mjs");
+  const app = await startApp();
+  const stop = async () => { await app.stop(); process.exit(0); };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  try {
+    // Fixtures run between the two sign-ins, so an invite-only app can admit the user first.
+    const sessions = { admin: await app.signIn(app.owner) };
+    if (values.fixtures) await (await import(pathToFileURL(resolve(values.fixtures)).href)).default({ ...app, sessions, user: values.user });
+    sessions.user = await app.signIn(values.user);
+    const lines = [`visitor (anonymous): ${app.origin}`];
+    for (const [role, cookie] of Object.entries(sessions)) {
+      const url = await proxy(app.origin, cookie);
+      lines.push(`${role} (${role === "admin" ? app.owner : values.user}): ${url}  MCP ${url}/mcp${role === "admin" ? "/admin" : ""}${role === "admin" ? `  Admin ${url}/admin` : ""}`);
+    }
+    console.log(lines.join("\n") + "\nReady. Ctrl-C stops the app and deletes its data.");
+  } catch (error) {
+    console.error(app.logs().slice(-4000));
+    await app.stop();
+    throw error;
+  }
+}
+
+/** A local origin that forwards to the app with one role's session; sliding Set-Cookie updates stay inside the proxy. */
+function proxy(origin, cookie) {
+  const jar = new Map(cookie.split("; ").map(pair => [pair.slice(0, pair.indexOf("=")), pair]));
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url, origin);
+    if (url.pathname.startsWith("/api/auth/")) { response.writeHead(403, { "content-type": "text/plain" }).end("Sign-in is handled by setup."); return; }
+    const chunks = [];
+    for await (const chunk of request) chunks.push(chunk);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) if (!["host", "cookie", "origin", "connection", "content-length"].includes(name)) headers.set(name, [value].flat().join(", "));
+    headers.set("cookie", [...jar.values()].join("; "));
+    headers.set("origin", origin);
+    const upstream = await fetch(url, { method: request.method, headers, redirect: "manual", body: chunks.length ? Buffer.concat(chunks) : undefined });
+    for (const set of upstream.headers.getSetCookie()) { const pair = set.split(";")[0]; jar.set(pair.slice(0, pair.indexOf("=")), pair); }
+    const out = {};
+    upstream.headers.forEach((value, name) => { if (!["set-cookie", "content-encoding", "content-length", "transfer-encoding"].includes(name)) out[name] = value; });
+    if (out.location) out.location = out.location.replace(origin, `http://${request.headers.host}`);
+    response.writeHead(upstream.status, out);
+    if (upstream.body) Readable.fromWeb(upstream.body).pipe(response); else response.end();
+  });
+  return new Promise(done => server.listen(0, "127.0.0.1", () => done(`http://127.0.0.1:${server.address().port}`)));
+}
+
+async function client(endpoint, tool, json) {
+  if (!endpoint) throw new Error("usage: node accept.mjs mcp <endpoint> [tool [json-arguments]]");
+  const headers = { "content-type": "application/json", accept: "application/json, text/event-stream" };
+  let id = 0;
+  const rpc = async (method, params) => {
+    const response = await fetch(endpoint, { method: "POST", headers, body: JSON.stringify({ jsonrpc: "2.0", ...(method.startsWith("notifications/") ? {} : { id: ++id }), method, params }) });
+    const session = response.headers.get("mcp-session-id");
+    if (session) headers["mcp-session-id"] = session;
+    const text = await response.text();
+    if (!response.ok && response.status !== 202) throw new Error(`MCP ${method}: HTTP ${response.status} ${text}`);
+    const data = text.split("\n").filter(line => line.startsWith("data:")).map(line => line.slice(5)).join("\n") || text;
+    return data ? JSON.parse(data) : null;
+  };
+  const init = await rpc("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "mantle-accept", version: "1" } });
+  headers["mcp-protocol-version"] = init.result?.protocolVersion ?? "2025-11-25";
+  await rpc("notifications/initialized");
+  if (!tool) {
+    const tools = [];
+    let cursor;
+    do { const page = (await rpc("tools/list", cursor ? { cursor } : {})).result; tools.push(...page.tools); cursor = page.nextCursor; } while (cursor);
+    console.log(JSON.stringify(tools, null, 2));
+  } else console.log(JSON.stringify(await rpc("tools/call", { name: tool, arguments: json ? JSON.parse(json) : {} }), null, 2));
+}

package/docs/examples/app-shell/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.wrangler/
+.dev.vars
+.env
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal

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

@@ -0,0 +1,43 @@
+{
+  "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 DB --local --file generated/schema.sql",
+    "db:seed": "wrangler d1 execute DB --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",
+    "accept": "node accept.mjs"
+  },
+  "dependencies": {
+    "@aotter/mantle": "0.2.0-alpha.10",
+    "@aotter/mantle-ui": "0.2.0-alpha.10",
+    "@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.10",
+    "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