@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/examples/host-chatgpt-sites/src/media.ts

@@ -1,109 +0,0 @@
-import type { Hono } from 'hono';
-import { DiagnosticError, makeDiagnostic } from '@aotter/mantle/spec';
-import { extensionForMime, type MediaStorage, type MediaAsset, type MediaVariant } from '@aotter/mantle/runtime';
-import type { AdminAuth } from '@aotter/mantle/admin';
-import type { Env } from './chatgpt-auth';
-
-const mimes = new Set(['image/jpeg', 'image/png', 'image/webp']);
-const groupPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-const filePattern = /^(primary|alternate|fallback)\.(jpg|png|webp)$/;
-
-type Pending = { expiresAt: number; variants: { mimeType: string; storageKey: string; expectedSize: number; maxBytes: number }[] };
-
-function failure(code: 'MEDIA_OBJECT_NOT_FOUND' | 'MEDIA_MIME_REJECTED' | 'MEDIA_VARIANT_SIZE_EXCEEDED') {
-  return new DiagnosticError(makeDiagnostic({code, phase:'runtime', severity:'error', path:'sites/R2MediaStorage'}));
-}
-
-/** Public media over the Sites R2 binding; no S3 credentials or public bucket URL. */
-export class SitesR2MediaStorage implements MediaStorage {
-  constructor(private readonly bucket:R2Bucket, private readonly origin:string) {}
-
-  async createUpload(args:Parameters<MediaStorage['createUpload']>[0]) {
-    const capabilities=args.variants.map(variant=>{
-      const storageKey=`${args.purpose}/${args.uploadGroupId}/${variant.role}.${extensionForMime(variant.mimeType)}`;
-      return {
-        mimeType:variant.mimeType, role:variant.role, method:'PUT' as const,
-        uploadUrl:`${this.origin}/admin/media-upload/${args.uploadGroupId}/${storageKey.split('/').at(-1)}`,
-        storageKey, publicUrl:`${this.origin}/media/${storageKey}`,
-        requiredHeaders:{'Content-Type':variant.mimeType},
-      };
-    });
-    return {uploadGroupId:args.uploadGroupId, capabilities, expiresAt:args.expiresAt};
-  }
-
-  async commitUpload(args:Parameters<MediaStorage['commitUpload']>[0]):Promise<MediaAsset> {
-    const checked=[] as {spec:(typeof args.variants)[number]; size:number}[];
-    for(const spec of args.variants) {
-      const head=await this.bucket.head(spec.storageKey);
-      if(!head)throw failure('MEDIA_OBJECT_NOT_FOUND');
-      if(head.httpMetadata?.contentType!==spec.mimeType)throw failure('MEDIA_MIME_REJECTED');
-      if(head.size>spec.maxBytes)throw failure('MEDIA_VARIANT_SIZE_EXCEEDED');
-      checked.push({spec,size:head.size});
-    }
-    const variants:MediaVariant[]=[];
-    for(const {spec,size} of checked) {
-      const object=await this.bucket.get(spec.storageKey);
-      if(!object)throw failure('MEDIA_OBJECT_NOT_FOUND');
-      await this.bucket.put(spec.storageKey,object.body,{
-        httpMetadata:{contentType:spec.mimeType},
-        customMetadata:{...object.customMetadata,committedAt:String(args.now),uploadGroupId:args.uploadGroupId,role:spec.role,filename:args.filename},
-      });
-      variants.push({mimeType:spec.mimeType,role:spec.role,storageKey:spec.storageKey,byteSize:size,publicUrl:await this.getPublicUrl({storageKey:spec.storageKey})});
-    }
-    return {id:args.uploadGroupId,variants,alt:args.alt,caption:args.caption,createdAt:args.now,metadata:{filename:args.filename}};
-  }
-
-  async getPublicUrl({storageKey}:Parameters<MediaStorage['getPublicUrl']>[0]) {return `${this.origin}/media/${storageKey}`;}
-  async deleteObject({storageKey}:Parameters<MediaStorage['deleteObject']>[0]) {await this.bucket.delete(storageKey);}
-}
-
-export function mountMedia(app:Hono<{Bindings:Env}>,auth:AdminAuth,env:Env) {
-  app.put('/admin/media-upload/:group/:file',async c=>{
-    const session=await auth.getSession(c.req.raw);
-    if(!session)return c.json({error:'unauthenticated'},401);
-    if(session.user.role!=='owner'&&session.user.role!=='editor')return c.json({error:'editor_required'},403);
-    if(c.req.header('origin')!==env.PUBLIC_ORIGIN)return c.json({error:'cross_origin'},403);
-    const group=c.req.param('group'),file=c.req.param('file');
-    if(!groupPattern.test(group)||!filePattern.test(file))return c.json({error:'invalid_upload'},400);
-    const row=await env.DB.prepare('SELECT record FROM pending_media_uploads WHERE id=?').bind(group).first<{record:string}>();
-    if(!row)return c.json({error:'upload_expired'},410);
-    const pending=JSON.parse(row.record) as Pending;
-    if(pending.expiresAt<=Date.now())return c.json({error:'upload_expired'},410);
-    const key=`content/${group}/${file}`;
-    const variant=pending.variants.find(v=>v.storageKey===key);
-    if(!variant||!mimes.has(variant.mimeType))return c.json({error:'invalid_upload'},400);
-    if(c.req.header('content-type')!==variant.mimeType)return c.json({error:'mime_rejected'},415);
-    const length=Number(c.req.header('content-length'));
-    if(Number.isFinite(length)&&length>variant.expectedSize)return c.json({error:'size_exceeded'},413);
-    if(!c.req.raw.body)return c.json({error:'empty_upload'},400);
-    // R2 put requires a fixed-length body. Bound memory to this validated 5 MB policy.
-    const reader=c.req.raw.body.getReader(),chunks:Uint8Array[]=[];
-    let bytes=0;
-    for(;;) {
-      const {done,value}=await reader.read();
-      if(done)break;
-      bytes+=value.byteLength;
-      if(bytes>variant.expectedSize){await reader.cancel();return c.json({error:'size_exceeded'},413);}
-      chunks.push(value);
-    }
-    if(bytes!==variant.expectedSize)return c.json({error:'size_mismatch'},400);
-    const body=new Uint8Array(bytes);
-    let offset=0;
-    for(const chunk of chunks){body.set(chunk,offset);offset+=chunk.byteLength;}
-    await env.MEDIA_BUCKET.put(key,body,{httpMetadata:{contentType:variant.mimeType}});
-    return c.body(null,204);
-  });
-
-  app.get('/media/:purpose/:group/:file',async c=>{
-    const {purpose,group,file}=c.req.param();
-    if(purpose!=='content'||!groupPattern.test(group)||!filePattern.test(file))return c.notFound();
-    const key=`${purpose}/${group}/${file}`;
-    const row=await env.DB.prepare('SELECT variants FROM media_assets WHERE id=?').bind(group).first<{variants:string}>();
-    if(!row)return c.notFound();
-    const variants=JSON.parse(row.variants) as MediaVariant[];
-    if(!variants.some(v=>v.storageKey===key))return c.notFound();
-    const object=await env.MEDIA_BUCKET.get(key);
-    if(!object||!mimes.has(object.httpMetadata?.contentType??''))return c.notFound();
-    return new Response(object.body,{headers:{'Content-Type':object.httpMetadata!.contentType!,'Content-Length':String(object.size),'Cache-Control':'public, max-age=3600','X-Content-Type-Options':'nosniff'}});
-  });
-}

package/docs/examples/host-chatgpt-sites/src/r2-lab.ts

@@ -1,38 +0,0 @@
-import type { Hono } from 'hono';
-import type { AdminAuth } from '@aotter/mantle/admin';
-import type { Env } from './chatgpt-auth';
-
-// Deliberately a binding probe, not an implementation of Mantle's public MediaStorage port.
-export function mountR2Lab(app:Hono<{Bindings:Env}>,auth:AdminAuth,env:Env) {
-  app.use('/admin/lab*',async(c,next)=>{
-    const session=await auth.getSession(c.req.raw);
-    if(!session)return c.json({error:'unauthenticated'},401);
-    if(session.user.role!=='owner')return c.json({error:'owner_required'},403);
-    if(c.req.method!=='GET'&&c.req.header('origin')!==env.PUBLIC_ORIGIN)return c.json({error:'cross_origin'},403);
-    await next();
-  });
-  app.get('/admin/lab',c=>c.html(`<!doctype html><html lang="zh-Hant"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>R2 驗證 · Mantle Sites</title><style>body{font:18px system-ui;max-width:760px;margin:60px auto;padding:24px;background:#101820;color:#eef5ff}a{color:#69dbff}button{font:inherit;padding:12px 20px;cursor:pointer}pre{white-space:pre-wrap}</style><h1>R2 binding 驗證</h1><p>以目前的 owner 身分寫入一個測試物件，在另一個請求讀取並核對內容，最後清理該物件。這不是媒體庫上傳測試。</p><button id="run">執行 R2 測試</button><pre id="result" role="status"></pre><a href="/admin">回管理後台</a><script>
-const button=document.querySelector('#run'),result=document.querySelector('#result');
-button.onclick=async()=>{button.disabled=true;result.textContent='測試中…';let id;try{
-const send=async(method,path)=>{const r=await fetch(path,{method});if(!r.ok)throw Error('HTTP '+r.status);return r.json()};
-const created=await send('POST','/admin/lab/r2');id=created.id;
-const read=await send('GET','/admin/lab/r2/'+id);if(!read.matches)throw Error('內容不一致');
-const deleted=await send('DELETE','/admin/lab/r2/'+id);if(!deleted.deleted)throw Error('清理未完成');id=null;
-result.textContent='PASS：R2 PUT → HEAD / GET（另一個請求）→ 內容核對 → DELETE / HEAD 確認已清理。';
-}catch(e){result.textContent='FAIL：'+e.message+(id?'；待清理測試 ID：'+id:'')}finally{button.disabled=false}};
-</script></html>`));
-  app.post('/admin/lab/r2',async c=>{
-    const id=crypto.randomUUID();
-    await env.MEDIA_BUCKET.put(`_sites_binding_probe/${id}`,`mantle-sites-r2:${id}`,{httpMetadata:{contentType:'text/plain'},customMetadata:{purpose:'disposable-binding-probe'}});
-    return c.json({id});
-  });
-  app.on(['GET','DELETE'],'/admin/lab/r2/:id',async c=>{
-    const id=c.req.param('id');
-    if(!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(id))return c.json({error:'invalid_id'},400);
-    const key=`_sites_binding_probe/${id}`,head=await env.MEDIA_BUCKET.head(key);
-    if(!head||head.customMetadata?.purpose!=='disposable-binding-probe')return c.json({error:'not_found'},404);
-    if(c.req.method==='DELETE'){await env.MEDIA_BUCKET.delete(key);return c.json({deleted:await env.MEDIA_BUCKET.head(key)===null});}
-    const object=await env.MEDIA_BUCKET.get(key);
-    return c.json({matches:!!object&&await object.text()===`mantle-sites-r2:${id}`,size:head.size});
-  });
-}

package/docs/examples/host-chatgpt-sites/src/storage-fingerprint.json

@@ -1 +0,0 @@
-"9ef85f9933e22328140e924045820af6be2a6985ed8ecc19b63a4f2a37826618"

package/docs/examples/host-chatgpt-sites/src/web.ts

@@ -1,35 +0,0 @@
-import type { Hono } from 'hono';
-import type { MantleAdminRuntime } from '@aotter/mantle/admin';
-import { createMantleWeb, createPublicPathResolver, composeEntrySeoMeta, composePageSeoMeta, renderSeoTagsHtml, serializeEntryAsMarkdown, TemplateRegistry } from '@aotter/mantle-web';
-import { micromark } from 'micromark';
-import type { Env } from './chatgpt-auth';
-
-const paths=createPublicPathResolver({collectionRoutes:{articles:{segment:'articles'}}});
-const escape=(value:unknown)=>String(value??'').replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]!));
-const articlePath=(id:string)=>`/articles/${encodeURIComponent(id)}`;
-const shell=(title:string,head:string,body:string)=>`<!doctype html><html lang="zh-Hant"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escape(title)}</title>${head}<link rel="stylesheet" href="/site.css"><style>.article-cover{margin:36px 0}.article-cover img{display:block;width:100%;height:auto;border-radius:12px}.prose img{max-width:100%;height:auto}</style></head><body><header class="topbar"><a class="brand" href="/"><span class="mark">M</span><span>Mantle <em>×</em> Sites</span></a><nav aria-label="主要導覽"><a href="/articles">文章</a><a href="/admin">管理後台 ↗</a></nav></header>${body}<footer><span>Mantle on ChatGPT Sites</span><a href="/llms.txt">給 AI 的內容索引</a></footer></body></html>`;
-const templates=new TemplateRegistry();
-templates.registerListTemplate('articles',({entries,nextPageUrl})=>`<section class="article-list">${entries.length?entries.map(entry=>`<article class="article-row"><div class="article-number">${new Date(entry.updatedAt).toLocaleDateString('zh-TW',{timeZone:'UTC'})}</div><div><h2><a href="${articlePath(entry.id)}">${escape(entry.data.title)}</a></h2><p>${escape(entry.data.summary||'閱讀完整文章')}</p></div><span aria-hidden="true">↗</span></article>`).join(''):'<div class="empty"><h2>文章準備中</h2><p>在管理後台發布文章後，就會自動出現在這裡。</p></div>'}</section>${nextPageUrl?`<nav class="pagination" aria-label="分頁"><a rel="next" href="${escape(nextPageUrl)}">更多文章 →</a></nav>`:''}`);
-
-export function mountWeb(app:Hono<{Bindings:Env}>,get:()=>Promise<MantleAdminRuntime>) {
-  const load=async()=>{const runtime=await get();return {runtime,site:await runtime.siteConfig.load(),web:createMantleWeb(runtime,{templates,paths})};};
-  const list=async(cursor?:string)=>{const {site,web}=await load();const seo=composePageSeoMeta({site,locale:'zh-TW',publicPath:'/articles',title:`文章｜${site.title}`,description:site.description||'由 Mantle 管理與發布的文章。',markdown:false,pathForLocale:()=>'/articles'});const page=await web.renderListLive.execute({collection:'articles',locale:'zh-TW',contentLocale:null,site,seo,cursor,limit:20,pathForPage:next=>`/articles?cursor=${encodeURIComponent(next)}`});return shell(`文章｜${site.title}`,renderSeoTagsHtml(seo),`<main><section class="hero small"><p class="eyebrow">THE JOURNAL</p><h1>文章與觀察<span class="dot">.</span></h1><p class="hero-copy">內容由 Mantle 後台管理，從 D1 即時讀取。</p></section><div class="content-wrap">${page?.html.replace(/^<!doctype html>/i,'')??''}</div></main>`);};
-  app.get('/',async c=>{const {site}=await load();const seo=composePageSeoMeta({site,locale:'zh-TW',publicPath:'/',title:site.title,description:site.description||'Mantle 在 ChatGPT Sites 上的內容實驗。',markdown:false,pathForLocale:()=>'/'});return c.html(shell(site.title,renderSeoTagsHtml(seo),`<main><section class="hero"><p class="eyebrow">BUILT WITH MANTLE · RUNNING ON CHATGPT SITES</p><h1>內容、資料、<br>與下一種網站<span class="dot">.</span></h1><p class="hero-copy">這個站點連接 Mantle 管理後台與 Sites 的 D1 資料庫。文章發布後，會自動生成可閱讀、可索引的頁面。</p><div class="actions"><a class="button" href="/articles">探索文章 <span>↗</span></a><a class="text-link" href="/admin">進入管理後台 →</a></div></section><section class="feature-grid" aria-label="網站能力"><div><span class="feature-index">01 / CONTENT</span><h2>一處編輯</h2><p>文章在 Mantle 後台建立與發布，前台直接讀取同一份內容。</p></div><div><span class="feature-index">02 / DISCOVERY</span><h2>搜尋與 AI 可讀</h2><p>標準 metadata、結構化資料、Markdown 鏡像與內容索引。</p></div><div><span class="feature-index">03 / PLATFORM</span><h2>託管於 Sites</h2><p>D1 保存文章，R2 圖片可在後台上傳並綁定文章封面。</p></div></section></main>`));});
-  app.get('/articles',async c=>c.html(await list(c.req.query('cursor'))));
-  app.get('/articles/:id',async c=>{const {runtime,site}=await load();const rawId=c.req.param('id');const markdown=rawId.endsWith('.md');const entry=await runtime.entries.readById({collection:'articles',id:markdown?rawId.slice(0,-3):rawId});if(!entry||entry.status!=='published')return c.notFound();if(markdown){const text=serializeEntryAsMarkdown(entry);return text?c.text(text,200,{'Content-Type':'text/markdown; charset=utf-8'}):c.notFound();}
-    const coverId=typeof entry.data.coverAssetId==='string'?entry.data.coverAssetId:'';
-    const cover=coverId?await runtime.media?.resolve(coverId):null;
-    const primary=cover?.variants.find(v=>v.role==='primary');
-    const coverUrl=primary?.publicUrl;
-    const seoEntry=coverUrl?{...entry,data:{...entry.data,coverUrl}}:entry;
-    const path=articlePath(entry.id),seo=composeEntrySeoMeta({entry:seoEntry,site,publicPath:path,locale:'zh-TW',type:'article'});
-    const title=String(entry.data.title??site.title);
-    const image=coverUrl?`<figure class="article-cover"><img src="${escape(coverUrl)}" alt="${escape(cover?.alt||title)}" loading="eager"></figure>`:'';
-    const body=micromark(String(entry.data.body??''),{allowDangerousHtml:false,allowDangerousProtocol:false});
-    return c.html(shell(`${title}｜${site.title}`,renderSeoTagsHtml(seo),`<main class="article-page"><a class="back" href="/articles">← 返回文章</a><article><p class="eyebrow">ARTICLE · ${new Date(entry.updatedAt).toLocaleDateString('zh-TW',{timeZone:'UTC'})}</p><h1>${escape(title)}</h1>${entry.data.summary?`<p class="lede">${escape(entry.data.summary)}</p>`:''}${image}<div class="prose">${body}</div></article></main>`));});
-  // ponytail: one discovery page is enough for this lab; expose cursor pages when published articles exceed the SDK page limit.
-  app.get('/llms.txt',async c=>{const {site,web}=await load();const page=await web.composeLlmsTxt.execute({collections:['articles'],locale:null,site,pathFor:e=>articlePath(e.id)});const body=page?.body??`# ${site.title}\n\n文章索引：${site.origin}/articles\n`;return c.text(body,200,{'Content-Type':'text/plain; charset=utf-8'});});
-  // ponytail: first 1000 published URLs; add sitemap index parts only when the catalogue reaches that ceiling.
-  app.get('/sitemap.xml',async c=>{const {site,web}=await load();const page=await web.composeSitemap.execute({site,collections:['articles'],pathFor:e=>articlePath(e.id),additionalPaths:['/','/articles'],maxUrls:1000});return c.text(page.body,200,{'Content-Type':'application/xml; charset=utf-8'});});
-  app.get('/robots.txt',async c=>c.text(`User-agent: *\nAllow: /\nSitemap: ${c.env.PUBLIC_ORIGIN}/sitemap.xml\n`));
-}

package/docs/examples/host-chatgpt-sites/tsconfig.json

@@ -1 +0,0 @@
-{"compilerOptions":{"target":"ES2022","module":"ESNext","moduleResolution":"Bundler","strict":true,"skipLibCheck":true,"noEmit":true,"types":["@cloudflare/workers-types"],"lib":["ES2022","DOM"]},"include":["src/**/*.ts",".mantle/generated/**/*.ts"]}

package/docs/examples/host-chatgpt-sites/wrangler.jsonc

@@ -1,10 +0,0 @@
-{
-  "name": "mantle-sites-reference",
-  "main": "dist/server/index.js",
-  "compatibility_date": "2026-09-08",
-  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
-  "assets": {"directory":"dist/client","binding":"ASSETS","run_worker_first":true},
-  "d1_databases": [{"binding":"DB","database_name":"mantle-sites-reference-local","database_id":"local","migrations_dir":"drizzle"}],
-  "r2_buckets": [{"binding":"MEDIA_BUCKET","bucket_name":"mantle-sites-reference-local-media"}],
-  "vars": {"PUBLIC_ORIGIN":"http://localhost:4174","OWNER_EMAIL":"owner@example.test"}
-}

package/docs/examples/host-local-admin-otp/.dev.vars.example

@@ -1,3 +0,0 @@
-PUBLIC_ORIGIN=http://127.0.0.1:8787
-BETTER_AUTH_SECRET=local-admin-otp-dev-secret-do-not-use-in-prod
-ADMIN_EMAIL=owner@example.com

package/docs/examples/host-local-admin-otp/README.md

@@ -1,80 +0,0 @@
-# Local Admin OTP
-
-This is the opt-in Dev UI path: a directly authored Cloudflare application
-that opens Mantle Admin locally with email OTP. Admin is not required to
-ship a complete service. It is not a Starter or CLI generator. Business
-Manifests live in the [Examples hub](../README.md). The notes
-Schema is example business data; `mantle generate` never invents it.
-
-Spec + adapter without Admin:
-[`docs/examples/host-minimal-worker`](../host-minimal-worker/README.md).
-
-This reference depends on every `@aotter/mantle*` package via the `latest`
-dist-tag, so a fresh install always resolves the current stable release.
-Core's test runner substitutes its exact candidate in a disposable copy.
-
-## One-shot
-
-Outside the SDK workspace, with Node 22+ and pnpm 9+:
-
-```sh
-pnpm install && pnpm generate && pnpm dev
-```
-
-`predev` copies `.dev.vars.example` to `.dev.vars` when that file is
-missing. `pnpm dev` binds `127.0.0.1:8787` so wrangler's Ready-on origin
-matches `PUBLIC_ORIGIN` (`http://127.0.0.1:8787`). Open that Ready-on
-URL. Browsing `http://localhost:8787` still serves HTML, but the OTP
-Origin header mismatches `PUBLIC_ORIGIN` and Better Auth returns
-`INVALID_ORIGIN`. Then:
-
-1. Open `http://127.0.0.1:8787/admin/sign-in`.
-2. Sign in with the bootstrap owner email from `.dev.vars` (`owner@example.com`
-   in the example).
-3. Read the one-time code from the wrangler log line
-   `[ConsoleEmailSender] auth.email-otp.sign-in → …`.
-4. Land in the Admin / Dev UI as `owner`.
-
-`mantle generate` syncs the prebuilt Admin SPA from `@aotter/mantle-admin-ui`
-into `public/_mantle/admin/`. There is no Vite or frontend build step unless
-you are developing `admin-ui` itself.
-
-## Hard requirements for Admin
-
-Admin is not a Worker route that paints itself. These must all be present:
-
-| Piece | Why |
-|---|---|
-| `@aotter/mantle-admin` and `@aotter/mantle-admin-ui` | Admin API plus the prebuilt SPA |
-| `assets.directory = ./public` and `binding = ASSETS` | Serves `/_mantle/admin/assets/*` |
-| `createAuth` `email-otp` + `ConsoleEmailSender` | Local human sign-in; code is in wrangler logs |
-| `bootstrapOwner.match: email` | First matching sign-in becomes `owner` |
-| `PUBLIC_ORIGIN` and `BETTER_AUTH_SECRET` | Auth construction; copied from `.dev.vars.example` |
-
-If `/admin` returns HTML `200` while `/_mantle/admin/assets/*` is `404`, the
-SPA white-screens. That is a missing or misconfigured `ASSETS` binding, not a
-failed frontend build. Do not put `/_mantle` in `run_worker_first`; asset
-paths must fall through to Static Assets.
-
-`ConsoleEmailSender` is the local path only. Do not wire it in production.
-
-## Local traps
-
-- Prefer `http://127.0.0.1:8787` over `http://localhost:8787`. Wrangler still
-  serves HTML on localhost, but the OTP `Origin` header will not match
-  `PUBLIC_ORIGIN` and Better Auth returns `INVALID_ORIGIN`.
-- `pnpm check` runs `smoke.mjs`, which rewrites `.dev.vars` to a smoke-only
-  port (`18787`). Restore `.dev.vars` from `.dev.vars.example` (or delete it
-  and let `predev` recopy) before `pnpm dev`, or OTP will fail with
-  `INVALID_ORIGIN` against the Ready-on `8787` origin.
-
-## What this project does not do
-
-`/` is `404`: no visitor frontend is installed. Public GET
-`/api/views/published-notes` still works against fresh local D1. Conventional
-GitHub Auth (`MANTLE_AUTH_MODE`) is not used; the Worker replaces construction
-with `createAuth` while Core still owns `/admin` and `/api/auth/*`.
-
-Commit the resolved lockfile in a real application and use frozen installs
-afterwards. Configure a real D1 `database_id`, a production email sender, and
-secrets before any remote deploy. Never commit `.dev.vars`.

package/docs/examples/host-local-admin-otp/ensure-dev-vars.mjs

@@ -1,5 +0,0 @@
-import { copyFileSync, existsSync } from "node:fs";
-
-if (!existsSync(".dev.vars")) {
-  copyFileSync(".dev.vars.example", ".dev.vars");
-}

package/docs/examples/host-local-admin-otp/manifests/site.yaml

@@ -1,25 +0,0 @@
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata:
-  name: notes
-spec:
-  title: Notes
-  schema:
-    type: object
-    required: [title]
-    properties:
-      title: { type: string }
-  lifecycle: publishing
----
-apiVersion: cms.mantle.aotter.net/v1
-kind: View
-metadata:
-  name: published-notes
-spec:
-  surface: public
-  from: notes
-  cache: { sharedMaxAge: 3600 }
-  fields: [id, title]
-  filter:
-    eq: { field: status, value: published }
-  limit: 20

package/docs/examples/host-local-admin-otp/package.json

@@ -1,29 +0,0 @@
-{
-  "name": "mantle-local-admin-otp",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "generate": "mantle generate",
-    "validate": "mantle validate",
-    "typecheck": "tsc --noEmit",
-    "predev": "node ensure-dev-vars.mjs",
-    "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
-    "check": "node ensure-dev-vars.mjs && mantle generate && mantle generate --check && mantle validate && mantle skills && mantle skills --check && tsc --noEmit && node smoke.mjs"
-  },
-  "dependencies": {
-    "@aotter/mantle": "latest",
-    "@aotter/mantle-admin": "latest",
-    "@aotter/mantle-admin-ui": "latest",
-    "@aotter/mantle-cloudflare": "latest",
-    "better-auth": "1.7.2",
-    "hono": "^4.13.3",
-    "zod": "^4.5.4",
-    "aws4fetch": "^1.0.20"
-  },
-  "devDependencies": {
-    "@cloudflare/workers-types": "^5.20260907.1",
-    "typescript": "^6.0.3",
-    "wrangler": "^4.125.0"
-  },
-  "packageManager": "pnpm@9.15.0"
-}

package/docs/examples/host-local-admin-otp/public/.gitkeep

@@ -1 +0,0 @@
-# Static Assets root. `mantle generate` writes public/_mantle/admin/ here.

package/docs/examples/host-local-admin-otp/smoke.mjs

@@ -1,141 +0,0 @@
-import assert from "node:assert/strict";
-import { spawn } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
-
-await import("./ensure-dev-vars.mjs");
-
-const ownerEmail = "owner@example.com";
-const port = 18787;
-const origin = `http://127.0.0.1:${port}`;
-writeFileSync(".dev.vars", [
-  `PUBLIC_ORIGIN=${origin}`,
-  "BETTER_AUTH_SECRET=local-admin-otp-dev-secret-do-not-use-in-prod",
-  `ADMIN_EMAIL=${ownerEmail}`,
-  "",
-].join("\n"));
-const logs = [];
-
-const wrangler = spawn("pnpm", [
-  "exec",
-  "wrangler",
-  "dev",
-  "--local",
-  "--ip",
-  "127.0.0.1",
-  "--port",
-  String(port),
-  "--inspector-port",
-  "0",
-  "--persist-to",
-  ".wrangler/smoke",
-], {
-  env: { ...process.env, WRANGLER_SEND_METRICS: "false", CI: "1" },
-  stdio: ["ignore", "pipe", "pipe"],
-});
-
-const onLog = (chunk) => {
-  logs.push(String(chunk));
-};
-wrangler.stdout.on("data", onLog);
-wrangler.stderr.on("data", onLog);
-
-try {
-  await waitForReady(origin);
-  const signIn = await fetch(`${origin}/admin/sign-in`);
-  assert.equal(signIn.status, 200, `/admin/sign-in ${signIn.status}`);
-  const html = await signIn.text();
-  assert.match(html, /<!doctype html|<html/i);
-  const assets = [...html.matchAll(/(?:href|src)="(\/_mantle\/admin\/[^"]+)"/g)]
-    .map((match) => match[1])
-    .filter((path, index, all) => all.indexOf(path) === index);
-  assert.ok(assets.length > 0, "Admin HTML must reference /_mantle/admin assets");
-  for (const path of assets) {
-    const asset = await fetch(`${origin}${path}`);
-    assert.equal(asset.status, 200, `${path} ${asset.status}`);
-  }
-
-  const methods = await fetch(`${origin}/api/auth/methods`);
-  assert.equal(methods.status, 200);
-  assert.deepEqual(await methods.json(), { methods: [{ kind: "email-otp" }] });
-
-  const sent = await fetch(`${origin}/api/auth/email-otp/send-verification-otp`, {
-    method: "POST",
-    headers: { origin, "content-type": "application/json" },
-    body: JSON.stringify({ email: ownerEmail, type: "sign-in" }),
-  });
-  assert.equal(sent.status, 200, `send OTP ${sent.status} ${await sent.text()}`);
-  const otp = await waitForOtp();
-  const signedIn = await fetch(`${origin}/api/auth/sign-in/email-otp`, {
-    method: "POST",
-    headers: { origin, "content-type": "application/json" },
-    body: JSON.stringify({ email: ownerEmail, otp }),
-  });
-  assert.equal(signedIn.status, 200, `sign-in ${signedIn.status} ${await signedIn.text()}`);
-  const cookie = cookieHeader(signedIn);
-  assert.ok(cookie, "sign-in must set a session cookie");
-
-  const shell = await fetch(`${origin}/admin`, { headers: { cookie } });
-  assert.equal(shell.status, 200, `/admin ${shell.status}`);
-  const settings = await fetch(`${origin}/admin/api/site-settings`, { headers: { cookie } });
-  assert.equal(settings.status, 200, `/admin/api/site-settings ${settings.status}`);
-  const pkg = JSON.parse(readFileSync("node_modules/@aotter/mantle/package.json", "utf8"));
-  console.log(`Mantle ${pkg.version}: /admin assets 200, OTP ${otp} in wrangler logs, owner Admin shell 200`);
-} finally {
-  wrangler.kill("SIGTERM");
-  await waitForExit(wrangler);
-}
-
-function cookieHeader(response) {
-  const cookies = typeof response.headers.getSetCookie === "function"
-    ? response.headers.getSetCookie()
-    : [response.headers.get("set-cookie")].filter(Boolean);
-  return cookies.map((value) => value.split(";", 1)[0]).join("; ");
-}
-
-async function waitForReady(url) {
-  const deadline = Date.now() + 60_000;
-  while (Date.now() < deadline) {
-    if (wrangler.exitCode !== null) {
-      throw new Error(`wrangler exited ${wrangler.exitCode}\n${logs.join("")}`);
-    }
-    try {
-      const response = await fetch(`${url}/admin/sign-in`);
-      if (response.status === 200) return;
-    } catch {
-      // Worker still booting.
-    }
-    await delay(250);
-  }
-  throw new Error(`wrangler did not become ready\n${logs.join("")}`);
-}
-
-async function waitForOtp() {
-  const deadline = Date.now() + 15_000;
-  while (Date.now() < deadline) {
-    const match = logs.join("").match(/Your Mantle sign-in code: (\d{6})/);
-    if (match) return match[1];
-    await delay(100);
-  }
-  throw new Error(`OTP log line missing\n${logs.join("")}`);
-}
-
-function waitForExit(child) {
-  return new Promise((resolve) => {
-    if (child.exitCode !== null) {
-      resolve();
-      return;
-    }
-    const timer = setTimeout(() => {
-      child.kill("SIGKILL");
-      resolve();
-    }, 5_000);
-    child.once("exit", () => {
-      clearTimeout(timer);
-      resolve();
-    });
-  });
-}
-
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/docs/examples/host-local-admin-otp/src/index.ts

@@ -1,54 +0,0 @@
-import {
-  ConsoleEmailSender,
-  createAuth,
-  createMantleWorker,
-  type MantleCloudflareEnv,
-} from "@aotter/mantle/cloudflare";
-import { plan } from "../.mantle/generated/mantle.js";
-
-export interface Env extends MantleCloudflareEnv {
-  readonly ASSETS: Fetcher;
-  readonly BETTER_AUTH_SECRET: string;
-  readonly ADMIN_EMAIL: string;
-}
-
-const sender = new ConsoleEmailSender();
-
-export default createMantleWorker<Env>({
-  plan,
-  cacheScope: "local-admin-otp",
-  siteDefaults: (env) => ({
-    brand: "Local Admin",
-    title: "Local Admin",
-    origin: originOf(env),
-  }),
-  auth: (env) => {
-    const origin = originOf(env);
-    const secret = required(env.BETTER_AUTH_SECRET, "BETTER_AUTH_SECRET");
-    const ownerEmail = required(env.ADMIN_EMAIL, "ADMIN_EMAIL");
-    return createAuth({
-      database: env.DB,
-      baseURL: origin,
-      secret,
-      methods: [{ kind: "email-otp", sender }],
-      bootstrapOwner: { match: "email", value: ownerEmail },
-      oauthProvider: {
-        loginPage: "/admin/sign-in",
-        consentPage: "/oauth/consent",
-        scopes: ["mcp"],
-        mcpResource: `${origin}/mcp`,
-      },
-    });
-  },
-});
-
-function originOf(env: Env): string {
-  return env.PUBLIC_ORIGIN?.replace(/\/+$/, "") ?? "http://127.0.0.1:8787";
-}
-
-function required(value: string | undefined, name: string): string {
-  if (!value) {
-    throw new Error(`${name} is required. Copy .dev.vars.example to .dev.vars.`);
-  }
-  return value;
-}

package/docs/examples/host-local-admin-otp/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noEmit": true,
-    "skipLibCheck": true,
-    "types": [
-      "@cloudflare/workers-types"
-    ]
-  },
-  "include": [
-    "src/**/*.ts",
-    ".mantle/generated/**/*.ts"
-  ]
-}

package/docs/examples/host-local-admin-otp/wrangler.jsonc

@@ -1,23 +0,0 @@
-{
-  "$schema": "node_modules/wrangler/config-schema.json",
-  "name": "mantle-local-admin-otp",
-  "main": "src/index.ts",
-  "compatibility_date": "2026-09-08",
-  "compatibility_flags": [
-    "nodejs_compat",
-    "global_fetch_strictly_public"
-  ],
-  "observability": {
-    "enabled": true
-  },
-  "assets": {
-    "directory": "./public",
-    "binding": "ASSETS"
-  },
-  "d1_databases": [
-    {
-      "binding": "DB",
-      "database_name": "mantle-local-admin-otp"
-    }
-  ]
-}

package/docs/examples/host-minimal-worker/README.md

@@ -1,41 +0,0 @@
-# Minimal Worker reference
-
-This is a directly authored, API-only application and executable consumer test.
-It is not a Starter, template catalog or CLI generator. Admin is opt-in; this
-reference has none. When humans need a console, see
-[`docs/examples/host-local-admin-otp`](../host-local-admin-otp/README.md). Business
-Manifests live in the [Examples hub](../README.md). The notes
-Schema/View is example business data; `mantle generate` never invents it.
-
-For your own project, author package.json, manifests, Worker/provider config
-and TypeScript settings for your requirements. Pin all selected `@aotter/mantle*`
-dependencies to the same intended release. The checked-in `latest` values are
-placeholders for Core's disposable release test; resolve and pin one exact
-version before installing a copied application.
-
-Outside the SDK workspace, with Node 22+ and pnpm 9+:
-
-```sh
-MANTLE_VERSION=$(pnpm view @aotter/mantle@latest version)
-pnpm add --save-exact "@aotter/mantle@$MANTLE_VERSION" "@aotter/mantle-cloudflare@$MANTLE_VERSION"
-pnpm check
-pnpm dev
-```
-
-Commit the resolved lockfile in a real application and use frozen installs
-subsequently. `generate` writes `.mantle/generated/mantle.ts`; `skills` separately
-projects version-matched instructions. Public GET `/api/views/published-notes`
-returns an empty result against fresh local D1. `/` is 404: no visitor frontend
-is installed or rendered. Auth routes fail closed until auth is configured.
-No provider resources or secrets are needed for this local reference.
-The View declares a one-hour shared-cache hint and the Worker supplies the
-stable `minimal-worker-local` cache scope; authenticated requests remain private.
-
-`mantle-web` is optional runtime document composition; it does not generate a
-home page. Add application-owned routes/templates/frontend only when needed.
-Configure real D1 identity and the chosen auth mode before any remote deploy;
-never copy test names over an existing project's bindings or commit secrets.
-
-Maintainers run `pnpm check:worker-consumer` from the SDK root for exact packed
-packages. The release controller also runs the same check against public npm
-artifacts before promoting any public channel.