@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.2

package/docs/examples/cf-primitives-intake-hooks.md

@@ -1,319 +0,0 @@
----
-description: A public intake form with a Turnstile bot check before the write and an email notification after it.
----
-# Intake form with bot check and notification
-
-**Handler class:** cf-primitives · **Builder:** no · [Examples hub](./README.md). The Builder-safe Manifest (builtin create only) is [Intake form](./builtin-intake.md).
-
-This example collects a public request, verifies a Cloudflare Turnstile token before the row is written, and notifies staff after it is written. Two lifecycle Triggers and two small handlers sit on a declarative intake Schema. Read it if you need any form that anonymous visitors submit.
-
-## Problem
-
-Visitors submit a name, an email address and a message. Staff read recent submissions in Admin, over the staff View REST route, or through Staff MCP. The public write must reject automated submissions before anything is stored, and a new row should trigger an email to the team without making the visitor wait for it or fail when email is not configured. Submissions are live records, not authored content, so the Schema is `operational`.
-
-## Manifest
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: requests
-spec:
-  title: Requests
-  description: Requests submitted through the public intake flow.
-  lifecycle: operational
-  schema:
-    type: object
-    additionalProperties: false
-    required: [name, email, message]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      message: { type: string, minLength: 1, maxLength: 2000 }
-      submittedAt: { type: number, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: recent-requests
-spec:
-  title: Recent requests
-  surface: staff
-  from: requests
-  fields: [id, name, email, message, submittedAt]
-  orderBy:
-    - { field: submittedAt, direction: desc }
-  limit: 50
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: submit-request
-spec:
-  title: Submit request
-  description: Create a new public request.
-  input:
-    type: object
-    additionalProperties: false
-    required: [name, email, message]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      message: { type: string, minLength: 1, maxLength: 2000 }
-      turnstileToken: { type: string }
-  output: { type: object }
-  handler: { kind: builtin, op: create, schema: requests }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: submit-request-http
-spec:
-  source: { kind: http, method: POST, path: /api/requests }
-  target: { procedure: submit-request }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: submit-request-mcp
-spec:
-  source: { kind: mcp, surface: public }
-  target: { procedure: submit-request }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: verify-turnstile
-spec:
-  input:
-    type: object
-    properties:
-      turnstileToken: { type: string }
-  output: { type: object }
-  handler: { kind: ref, ref: verify-turnstile }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: 010-requests-verify-turnstile
-spec:
-  source:
-    kind: lifecycle
-    schema: requests
-    on: [before_create]
-    errorPolicy: abort
-  target: { procedure: verify-turnstile }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Procedure
-metadata:
-  name: notify-request
-spec:
-  input:
-    type: object
-    properties:
-      name: { type: string }
-      email: { type: string }
-      message: { type: string }
-  output: { type: object }
-  handler: { kind: ref, ref: notify-request }
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: Trigger
-metadata:
-  name: 020-requests-notify
-spec:
-  source:
-    kind: lifecycle
-    schema: requests
-    on: [after_create]
-    errorPolicy: continue
-  target: { procedure: notify-request }
-```
-
-Three details carry the pattern:
-
-- `submit-request.input` declares `turnstileToken` even though the `requests` Schema does not. The builtin `create` projects `input ∩ Schema.properties`, so the token is never stored. Because the input sets `additionalProperties: false`, the token must be declared or the request fails with `INPUT_VALIDATION_FAILED`.
-- `before_create` hooks receive the original, pre-projection input, so `verify-turnstile` can read the token. Its own `input` schema must not set `additionalProperties: false`; it receives `name`, `email` and `message` too.
-- `after_create` hooks receive the persisted `entry.data`. The token is gone by then, which is why verification cannot be an `after_*` hook.
-
-Lifecycle Triggers on the same `(schema, hook)` run alphabetically by `metadata.name`; the `010-`/`020-` prefixes make the order explicit. See [Writes: Procedures, Triggers and hooks](../handbook/concepts/procedures-and-triggers.md).
-
-## Worker and handlers
-
-```ts
-// src/handlers.ts
-import { InvokeFailure, type HandlerContext } from "@aotter/mantle/runtime";
-import { runtimeDiagnostic } from "@aotter/mantle/spec";
-import type { Env } from "./index.js";
-
-interface SiteverifyResult {
-  readonly success?: boolean;
-  readonly "error-codes"?: readonly string[];
-}
-
-export async function verifyTurnstile(
-  input: { readonly turnstileToken?: string },
-  ctx: HandlerContext<Env>,
-): Promise<{ ok: true }> {
-  const secret = ctx.env.TURNSTILE_SECRET_KEY?.trim();
-  if (!secret) return { ok: true }; // fail-open until the secret exists; see below
-
-  const token = input.turnstileToken?.trim();
-  if (!token) reject("Turnstile verification is required.");
-
-  const body = new FormData();
-  body.set("secret", secret);
-  body.set("response", token);
-  const response = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
-    method: "POST",
-    body,
-  });
-  const result = response.ok
-    ? ((await response.json().catch(() => null)) as SiteverifyResult | null)
-    : null;
-  if (!result?.success) reject("Turnstile verification failed.", result?.["error-codes"]);
-  return { ok: true };
-}
-
-function reject(message: string, value?: unknown): never {
-  throw new InvokeFailure(
-    runtimeDiagnostic({
-      code: "LIFECYCLE_HOOK_REJECTED",
-      severity: "error",
-      path: "/turnstileToken",
-      value,
-      expected: "a valid Cloudflare Turnstile token",
-      message,
-    }),
-  );
-}
-
-export async function notifyRequest(
-  input: { readonly name?: string; readonly email?: string; readonly message?: string },
-  ctx: HandlerContext<Env>,
-): Promise<{ ok: true }> {
-  const { EMAIL, INTAKE_NOTIFY_TO, INTAKE_NOTIFY_FROM } = ctx.env;
-  if (!EMAIL || !INTAKE_NOTIFY_TO || !INTAKE_NOTIFY_FROM) {
-    console.info("[requests] notification not configured", { entry: ctx.event?.entry?.id });
-    return { ok: true }; // fail-soft: the row is already committed
-  }
-  await EMAIL.send({
-    to: INTAKE_NOTIFY_TO,
-    from: INTAKE_NOTIFY_FROM,
-    subject: `New request from ${input.name ?? "website"}`,
-    text: [`Name: ${input.name ?? ""}`, `Email: ${input.email ?? ""}`, "", input.message ?? ""].join("\n"),
-    ...(input.email ? { replyTo: input.email } : {}),
-  });
-  return { ok: true };
-}
-```
-
-```ts
-// src/index.ts
-import { createMantleWorker, type MantleCloudflareEnv } from "@aotter/mantle/cloudflare";
-import { plan, type MantleHandlers } from "../.mantle/generated/mantle.js";
-import { notifyRequest, verifyTurnstile } from "./handlers.js";
-
-interface EmailBinding {
-  send(message: { to: string; from: string; subject: string; text?: string; replyTo?: string }): Promise<unknown>;
-}
-
-export interface Env extends MantleCloudflareEnv {
-  readonly TURNSTILE_SECRET_KEY?: string;
-  readonly EMAIL?: EmailBinding;
-  readonly INTAKE_NOTIFY_TO?: string;
-  readonly INTAKE_NOTIFY_FROM?: string;
-}
-
-const handlers = {
-  "verify-turnstile": verifyTurnstile,
-  "notify-request": notifyRequest,
-} satisfies MantleHandlers<Env>;
-
-export default createMantleWorker<Env>({ plan, extend: () => ({ handlers }) });
-```
-
-The keys of `handlers` are the opaque `handler.ref` strings from the Manifest. A missing key fails at boot with `HANDLER_NOT_REGISTERED`.
-
-Bindings live in `wrangler.toml`: `[[send_email]] name = "EMAIL"` for Cloudflare Email Service, `INTAKE_NOTIFY_TO` and `INTAKE_NOTIFY_FROM` as vars, and `TURNSTILE_SECRET_KEY` as a secret (`wrangler secret put TURNSTILE_SECRET_KEY`). See [Bindings and primitives](../handbook/cloudflare/bindings.md).
-
-Two policies are deliberate and reversible:
-
-- **Bot check fails open when the secret is unset.** A first deployment without Turnstile configured still accepts submissions instead of rejecting every visitor with an opaque error. To fail closed, replace `if (!secret) return { ok: true }` with `if (!secret) reject("Turnstile is not configured.")`.
-- **Notification fails soft.** The Trigger's `errorPolicy: continue` means a throwing `after_create` handler is logged and never rolls back the row; the handler additionally returns `ok` when the binding is absent so logs stay quiet. If you later route `after_*` hooks through a Queue, keep the handler idempotent as described in [Deferred hooks with Queues](../handbook/cloudflare/deferred-hooks-queues.md).
-
-> **Warning**
-> The runtime does not substitute an error code when a `before_*` hook aborts; the caller receives exactly the diagnostic the hook threw. This handler throws `LIFECYCLE_HOOK_REJECTED` (409). Throwing `INPUT_VALIDATION_FAILED` (400) is equally valid if you prefer to treat a missing token as a malformed request.
-
-## Try it
-
-Submit a request:
-
-```sh
-curl -sS -X POST http://localhost:8787/api/requests \
-  -H 'content-type: application/json' \
-  -d '{"name":"Ada","email":"ada@example.test","message":"Please call me back.","turnstileToken":"<token>"}'
-```
-
-```json
-{
-  "ok": true,
-  "data": {
-    "id": "req_01j...",
-    "collection": "requests",
-    "status": "published",
-    "version": 1,
-    "data": { "name": "Ada", "email": "ada@example.test", "message": "Please call me back.", "submittedAt": 1788879363492 },
-    "authorId": null,
-    "createdAt": 1788879363492,
-    "updatedAt": 1788879363492
-  }
-}
-```
-
-The builtin `create` returns the `EntryRow`; `status` is `published` immediately because the Schema is operational. A rejected token, with the secret configured:
-
-```json
-{
-  "ok": false,
-  "diagnostic": {
-    "code": "LIFECYCLE_HOOK_REJECTED",
-    "phase": "runtime",
-    "severity": "error",
-    "path": "/turnstileToken",
-    "expected": "a valid Cloudflare Turnstile token",
-    "message": "Turnstile verification failed."
-  }
-}
-```
-
-That response is HTTP 409 and no row exists. A missing `name` is HTTP 400 `INPUT_VALIDATION_FAILED` before any hook runs.
-
-Staff read the queue at `GET /admin/api/views/recent-requests?page=1&show=50` with a staff session; the envelope is `{ ok, data: { rows, page, show, hasMore } }`.
-
-MCP tools:
-
-| Surface | Tool | Origin |
-|---|---|---|
-| `/mcp` | `submit_request` | `submit-request-mcp` Trigger |
-| `/mcp/staff` | `query_view_recent_requests` | `recent-requests` View |
-| `/mcp/staff` | `create_record_requests`, `update_record_requests` | operational Schema `requests` |
-
-An agent calling `submit_request` on `/mcp` has no browser Turnstile widget. With the secret unset the call succeeds; with the secret set it is rejected unless the agent supplies a valid token. Keep or remove `submit-request-mcp` deliberately.
-
-## What this deliberately leaves out
-
-- **Deduplication.** Two identical submissions create two rows. Add a `uniqueIndexes` tuple or a `before_create` lookup if duplicates matter.
-- **Rate limiting beyond Turnstile.** The adapter applies its own request limits to Auth and Admin routes, not a per-form quota.
-- **CRM sync.** Forwarding rows to an external system belongs in another `after_create` handler, ideally deferred through a Queue with the `${ctx.event.id}:${ctx.event.trigger}` idempotency key.
-
-Related: [Reservation requests](./builtin-reservation.md) uses the same builtin-create shape without hooks; [Procurement approvals](./builtin-procurement.md) adds member and staff roles.
-
-## Source
-
-- [Procedure reference](../handbook/reference/procedure.md) — builtin table, side-channel input fields, lifecycle hooks
-- [`packages/mantle-runtime/src/usecase/lifecycle/RunLifecycleHooksUseCase.ts`](../../packages/mantle-runtime/src/usecase/lifecycle/RunLifecycleHooksUseCase.ts) — abort propagates the hook's diagnostic
-- [`packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts`](../../packages/mantle-runtime/src/usecase/procedure/InvokeProcedureUseCase.ts) — `InvokeFailure`
-- [`packages/mantle-spec/src/kernel/diagnostic.ts`](../../packages/mantle-spec/src/kernel/diagnostic.ts) — `LIFECYCLE_HOOK_REJECTED` → 409
-- [`packages/adapters/cloudflare/src/handlers/turnstile.ts`](../../packages/adapters/cloudflare/src/handlers/turnstile.ts) — Turnstile verification helper

package/docs/examples/host-chatgpt-sites/.openai/hosting.json

@@ -1 +0,0 @@
-{"d1":"DB","r2":"MEDIA_BUCKET"}

package/docs/examples/host-chatgpt-sites/README.md

@@ -1,70 +0,0 @@
-# Mantle on ChatGPT Sites: runnable reference
-
-The runnable application for [Mantle on ChatGPT Sites](../../handbook/chatgpt-sites/index.md) connects Sites D1 + R2 bindings, Sign in with ChatGPT identity, Mantle Admin and staff roles, same-origin media upload, a published-only article frontend, anonymous read-only `/api/mcp`, and Sites-session staff tools at `/api/mcp/staff`. Remote OAuth MCP remains a separate integration; see [MCP support](../../handbook/chatgpt-sites/host-reference.md#remote-mcp-is-a-separate-gate).
-
-After setup, follow [Publish your first article](../../handbook/chatgpt-sites/index.md#publish-your-first-article) to verify the editorial workflow in Admin, then [maintain content with an agent](../../handbook/chatgpt-sites/index.md#maintain-content-with-an-agent). Article pages advertise their Markdown mirror through an HTML `rel="alternate"` link; the example does not add a visible Markdown button to the reader UI.
-
-## Before writing code
-
-Read the user's business request and author the manifest for **their** records and lifecycle. The included `articles` example deliberately allows a title-only draft; `body` uses `x-mcp-hint: markdown`, while `coverAssetId` uses both `x-mantle-ref: media_assets` (Admin picker) and `x-mcp-hint: media-image` (agent guidance). The `published-articles` View is a list projection, not the detail page contract. If the user's content must always have a body, add it to `required`; if the public API must return body or cover ID, add those to the View's `fields`. Review staff roles, public filters and indexes before deployment. `mantle validate` checks grammar, **not** whether this model matches the business request. Manifest changes after deployment require a new reviewed D1 migration and matching storage fingerprint; never edit an applied migration.
-
-## Install and run
-
-Requires Mantle 0.1.2 or newer. Copy this directory from the selected installed SDK version into a new application directory. Replace every `@aotter/mantle*` `latest` dependency in `package.json` with that same exact version, then:
-
-```bash
-npm install                                  # or: bun install
-npx mantle validate --phase deploy           # or: bunx mantle ...
-npm run generate && npm run check
-npx wrangler d1 migrations apply DB --local
-npm run dev -- --port 4174                   # leave running
-npm test                                     # smoke, in a second terminal
-```
-
-This example does not commit a lockfile. Commit the lockfile created by your
-first install and use `npm ci` for subsequent installs. `bun install` also
-works when you use Bun's lockfile consistently.
-
-## Add a manifest HTTP Trigger
-
-Mounting Admin does not register a manifest HTTP Trigger on the Site's Hono
-router. For an anonymous JSON form whose Trigger declares `POST /api/rsvp`, add
-the corresponding route inside `assemble` in `src/index.ts`:
-
-```ts
-import { createMantleRequestHandler } from '@aotter/mantle/runtime';
-
-const handleHttp = createMantleRequestHandler({ plan, getRuntime: get });
-app.post('/api/rsvp', async c =>
-  (await handleHttp(c.req.raw, { user: null, staff: null, env: c.env }))
-    ?? new Response('Not found', { status: 404 }));
-```
-
-Return the handler's `Response` directly: it validates the JSON body and maps
-Mantle diagnostics to HTTP status codes. If the Trigger requires a signed-in
-user or staff role, derive that context from the verified Sites session instead
-of copying the anonymous context above. See [Procedures and Triggers](../../handbook/concepts/procedures-and-triggers.md#the-http-envelope).
-
-Keep `.openai/hosting.json`; do not copy an existing Site's `project_id`. To use another port, also set the Worker's `PUBLIC_ORIGIN` and the test's `MANTLE_TEST_ORIGIN` to that same localhost origin. Local test headers simulate Sites' trusted dispatcher; they do **not** prove deployed ChatGPT login.
-
-Review the entire [smoke script](./scripts/check.mjs) before adapting it. It covers D1 CRUD/version conflict, owner/member/role revocation, R2 read/write/delete, media create → PUT → commit → public read, both advertised MCP URLs, public MCP `initialize`/`tools/list`/View call, staff MCP authentication/catalog, draft isolation, published article HTML/Markdown/SEO, and negative auth/Origin/size checks. It creates and deletes only its own test records and objects.
-
-The checked-in `drizzle/` migrations and `src/storage-fingerprint.json` match the example manifest and runtime. Apply all pending D1 migrations before deploying updated code; managed storage refuses to boot against an older database. After changing a Schema, first apply the current migrations to local D1, then run `npm run generate` and `npm run migrate:generate`. Review the newly appended SQL and apply it with `wrangler d1 migrations apply mantle-sites-reference-local --local`. Commit the new migration, `drizzle/meta/mantle-state.json`, journal, and fingerprint together. The generator checks the local database fingerprint before appending; it never changes an applied SQL file or applies D1 migrations itself. Deploy the reviewed migration before deploying code that expects its fingerprint.
-
-## Publish with Sites
-
-1. Create a new Site through Sites and request **both D1 and R2**. Confirm its saved hosting manifest has `d1: "DB"` and `r2: "MEDIA_BUCKET"`; the local example intentionally omits `project_id` until Sites provisions one. A missing R2 binding cannot be repaired by adding an R2 type to TypeScript. Sites controls provisioning and publishing, not `wrangler deploy`.
-2. In Sites settings, set `PUBLIC_ORIGIN` to the exact production origin and `OWNER_EMAIL` to the intended first owner. Do not commit hosted secrets or identity headers. Keep the Site audience narrow until verification. A Site Viewer is not automatically a Mantle staff member.
-3. Review the D1 migration, save a Sites version, then deploy that version. Every deployment URL is production. Confirm the deployed artifact includes `dist/server/index.js`, `dist/client/`, `dist/.openai/hosting.json` and `dist/.openai/drizzle/`; `npm run build` replaces `dist` before preparing those artifacts, so removed migrations cannot remain in a later build.
-4. On the deployed Site, check `/health`, `/admin/sign-in`, one `/_mantle/admin/assets/*` file, owner login and staff revocation, Admin media upload and committed public image URL, then publish an article with that asset as its cover. Anonymous draft and uncommitted image URLs must return 404. Check public HTML, Markdown, canonical/JSON-LD, sitemap and `llms.txt`; POST `/api/mcp` should discover only the public View tool, while `/api/mcp/staff` must reject anonymous/member requests and expose staff tools to a current staff session. The root `/mcp` path was intercepted in the lab and is not used by this reference.
-
-The media path uses only the R2 binding: `ports.mediaStorage` + `media.purposes` + authenticated same-origin PUT + committed-only public GET. It does not need an R2 S3 endpoint or API keys. The upload route is browser-session authenticated, so it is **not** an MCP agent upload route. Do not expose the Worker outside Sites' identity-stripping ingress: `src/chatgpt-auth.ts` trusts the `oai-*` headers only under that condition.
-
-## Stop conditions
-
-- `/admin/media` says storage is disabled: check **all three** of `r2` binding, `ports.mediaStorage`, and `media.purposes`; a successful R2 probe alone is insufficient.
-- Admin HTML loads but JS assets 404: check `dist/client/_mantle/admin/assets/` and `ASSETS` routing.
-- `/api/mcp/staff` uses the Sites-injected browser identity and re-reads the Mantle staff role. It is mounted and advertised in Admin, but it is not an OAuth resource server. Do not register it as a remote ChatGPT connector until OAuth discovery, a standards-compliant bearer challenge and token verification are implemented and tested.
-- OAuth discovery returns sign-in HTML: Sites' page session is not an OAuth bearer challenge. Do not bypass Sites auth or trust browser cookies as remote MCP credentials.
-
-See the [Sites host reference](../../handbook/chatgpt-sites/host-reference.md) and [OpenAI Sites documentation](https://learn.chatgpt.com/docs/sites).

package/docs/examples/host-chatgpt-sites/drizzle/0000_sites_users.sql

@@ -1,8 +0,0 @@
-CREATE TABLE sites_users (
-  id TEXT PRIMARY KEY NOT NULL,
-  email TEXT NOT NULL UNIQUE,
-  name TEXT NOT NULL,
-  role TEXT CHECK (role IN ('owner','editor','contributor') OR role IS NULL),
-  signed_in INTEGER NOT NULL DEFAULT 0,
-  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
-);