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

package/docs/examples/reservation.md

@@ -1,142 +0,0 @@
----
-description: Accept public reservation requests and expose the queue to staff. One SQL INSERT, no handler code.
----
-# Reservation requests
-
-[Examples hub](./README.md)
-
-Visitors ask for a reservation and staff confirm by hand. The manifests are
-fully declarative: the one Procedure is a SQL `INSERT`. Use this for
-appointments, bookings or table requests where a person decides.
-
-## Problem
-
-A visitor gives a name, an email address, the requested slot, an optional party
-size and a note. Staff see the newest requests first through Admin's API or the
-staff MCP surface, and follow up outside the system. Requests are records, so
-the Schema is `operational`. The system does not decide whether a slot is free.
-
-## Manifest
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: reservations }
-spec:
-  title: Reservations
-  lifecycle: operational
-  checks: ["partySize IS NULL OR partySize BETWEEN 1 AND 20"]
-  schema:
-    type: object
-    additionalProperties: false
-    required: [name, email, requestedFor]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      requestedFor: { type: string, description: Requested date, time or slot. }
-      partySize: { type: integer, minimum: 1 }
-      note: { type: string, maxLength: 1000 }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: reservation-queue }
-spec:
-  title: Reservation queue
-  surface: staff
-  requires: { auth: { all: [{ ctx.staff: [owner, editor, contributor] }] } }
-  sql: |
-    SELECT id, name, email, requestedFor, partySize, note, created_at
-    FROM reservations
-    ORDER BY created_at DESC LIMIT 50
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: submit-reservation }
-spec:
-  title: Submit reservation
-  description: Ask for a reservation; staff confirm it by hand.
-  input:
-    type: object
-    additionalProperties: false
-    required: [name, email, requestedFor]
-    properties:
-      name: { type: string, minLength: 1, maxLength: 120 }
-      email: { type: string, format: email }
-      requestedFor: { type: string }
-      partySize: { type: integer, minimum: 1 }
-      note: { type: string, maxLength: 1000 }
-  output: { type: object }
-  handler:
-    sql: |
-      INSERT INTO reservations (name, email, requestedFor, partySize, note)
-      VALUES (input.name, input.email, input.requestedFor, input.partySize, input.note)
-      RETURNING id
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: submit-reservation-http }
-spec:
-  source: { kind: http, method: POST, path: /api/reservations }
-  target: { procedure: submit-reservation }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: submit-reservation-mcp }
-spec:
-  source: { kind: mcp, surface: public }
-  target: { procedure: submit-reservation }
-```
-
-- `requestedFor` is a free string on purpose: the example imposes no calendar
-  model. The queue orders by the native `created_at`, so the newest request is
-  first whatever slot it asks for.
-- An optional input that the caller leaves out binds as `NULL`.
-- `checks` are boolean SQL over the row's own columns, enforced on every insert
-  and update, Admin's included. The input schema already refuses `partySize: 0`;
-  the check also caps the party for writes that do not come through this
-  Procedure.
-
-## Handlers
-
-None.
-
-## Try it
-
-```sh
-curl -sS -X POST http://127.0.0.1:8787/api/reservations \
-  -H 'content-type: application/json' \
-  -d '{"name":"Ada","email":"ada@example.test","requestedFor":"2026-10-03T19:00:00+08:00","partySize":4}'
-```
-
-The answer is `{ "results": [[{ "id": "…" }]] }`. A `partySize` of `0` is
-HTTP 400 `INPUT_VALIDATION_FAILED`; `25` fails the check, also with a 400.
-
-Staff list the queue at `GET /admin/api/views/reservation-queue?limit=50` with
-a staff session. `GET /admin/api/views/reservation-queue/export` returns the
-rows as CSV.
-
-| MCP surface | Tool | From |
-|---|---|---|
-| `/mcp` | `submit_reservation` | the `submit-reservation-mcp` Trigger |
-| `/mcp/staff` | `reservation_queue` | the staff View |
-
-## What this leaves out
-
-A successful `POST` records the request, nothing more.
-
-- **Slot inventory and double booking.** Two requests for one time both
-  succeed. With a `slots` Schema, a capacity column and `checks: ["booked <=
-  capacity"]`, a two-statement Procedure (insert the reservation, then
-  `UPDATE slots SET booked = booked + 1 WHERE id = input.slotId`) refuses the
-  overbooking atomically, as [Commerce inventory](./commerce-inventory.md) does
-  for stock.
-- **Past dates.** Reject them in a `requires.guard` handler, as
-  [Intake with bot check and notification](./intake-hooks.md) does for its
-  token.
-- **Calendar sync, payments and confirmation emails.** An `after_create` hook
-  as in the intake example.
-
-## Source
-
-- [Procedure reference](../handbook/reference/procedure.md)
-- [Schema reference](../handbook/reference/schema.md): `checks`

package/docs/skills/develop/mcp-app.md

@@ -1,79 +0,0 @@
-# Recipe: an MCP App for members
-
-The preset serves Mantle's App on `/mcp/staff` only. A member-facing App, on
-`/mcp`, is the application's: the SDK attaches none, because what a member
-should see in a chat (one order, a booking form, a status card) is a product
-decision. Build it case by case from these pieces.
-
-## Pieces
-
-| Piece | From | What it gives |
-|---|---|---|
-| `apps: { resources: [...] }` | `createMcpSurface` (`@aotter/mantle/mcp`) | a `ui://` resource beside the tools; `renders` names the tools whose results it shows, `appOnly` the View tools only the App may call |
-| `appCatalog(plan, "public")`, `withCatalog(html, catalog)` | `@aotter/mantle/mcp` | each public View tool's columns as the fields they read, and the row operations, embedded in your HTML as `#mantle-catalog` |
-| `planApp(plan, { surface: "public", html: mantleAppHtml })` | `@aotter/mantle/mcp`, `@aotter/mantle-ui/mcp-app` | the staff App as is, for every public View: the quickest start when a list is what you want |
-| `App` | `@modelcontextprotocol/ext-apps` | the host bridge: `ontoolresult`, `ontoolinput`, `callServerTool`, the host's locale and theme |
-| `readCatalog`, `toolOf`, `outputOf`, `rowsOf`, `invokeTool`, `actionsFor` | `@aotter/mantle-ui` | the catalog, a result's tool, its output and rows, and a tool call as the controller reads it, so the App never parses the wire itself |
-| `renderDataValue`, `propertyLabel`, `optionLabel`, `OperationPanel` | `@aotter/mantle-ui` | a value as Admin shows it (money, dates, option titles, in the host's locale), and Admin's review-and-submit panel |
-| `createInteractionController` | `@aotter/mantle-ui/controller` | one operation on one row: review, submit once, a refusal or `CONFLICT` kept, never retried |
-| `SchemaFields` and the primitives | `@aotter/mantle-ui/kit`, styled by `@aotter/mantle-ui/kit.css` | Admin's form controls |
-
-The App's own build installs what it imports: `@modelcontextprotocol/ext-apps`
-at the exact version `@aotter/mantle` depends on, React and the kit's peers
-(`@aotter/mantle-ui`'s README lists them). `docs/handbook/concepts/mcp-and-agents.md`
-(MCP Apps) describes the catalog and the staff App these share.
-
-## Steps
-
-1. Decide what the App shows and which tool's result opens it. It renders a
-   tool the surface already serves: a public View, or a Procedure with an
-   `mcp` Trigger on `public`. Add that Trigger or View first; an App never
-   reaches data a tool does not.
-2. Build one self-contained HTML file, for example `app/dist/member.html`:
-   Vite with `vite-plugin-singlefile` (and React, if you use the components).
-   A host loads the App in a sandbox that fetches nothing else unless the
-   resource's `csp` allows it. The build runs before `wrangler dev` and
-   deploy: add it to the project's scripts.
-3. Serve it. Wrangler imports `.html` as text; declare it for TypeScript in
-   `src/env.d.ts` (`declare module "*.html" { const html: string; export default html; }`),
-   then in `src/service.ts` (identity `mantle`, whose preset defines
-   `resourceMetadata`; with `custom`, pass the surface to your own `guard`):
-
-   ```ts
-   import memberHtml from "../app/dist/member.html";
-   import { appCatalog, withCatalog } from "@aotter/mantle/mcp";
-
-   const html = withCatalog(memberHtml, appCatalog(runtime.plan, "public"));
-   const mcp = guard(createMcpSurface(runtime, { basePath: "/mcp", surface: "public", resourceMetadata,
-     apps: { resources: [{ uri: "ui://shop/my-orders", name: "my-orders", html, renders: ["my_orders"] }] } }), { resourceMetadata });
-   ```
-
-4. In the App, `readCatalog()` once; in `ontoolresult`, `toolOf(result)` names
-   the tool and `outputOf(result)` (or `rowsOf` for a View) is its data. A
-   success is `structuredContent` when the output is an object and the JSON
-   text otherwise; a failure of a tool with an output schema is the text
-   alone, which `outputOf` reads either way. Call tools through
-   `invokeTool(app.callServerTool…)`: a refusal is `{ ok: false, diagnostics }`
-   (`AUTH_DENIED`, `CONFLICT`, ...), and a thrown call (a 401 or 403 from a
-   missing scope or sign-in, a lost connection) is an unknown outcome to
-   re-read, never to retry blindly.
-
-## Rules
-
-- The HTML is a static asset: no caller data, no secrets, the same for every
-  member. Caller data arrives only in tool results.
-- Every read and write is a tool call under the member's own token; `requires`
-  and `scope` apply exactly as they do to the model's calls.
-- `appOnly` hides a read from the model; only a View can be app-only, never a
-  write.
-- A public View over a `publishing` Schema shows published rows only; over a
-  `scope`d Schema it shows the caller's own rows, without a `WHERE` of yours.
-
-## Verify
-
-Add the App's build to the develop loop, then: `tools/list` from a client that
-declares the MCP Apps extension shows the rendered tool with
-`_meta.ui.resourceUri`; `resources/read` of that URI returns your HTML with
-`#mantle-catalog`; a call to the tool returns its result with
-`_meta["net.aotter.mantle/tool"]`. Then open it in a host that renders MCP
-Apps, signed in as a member.