@acms-subir/core 0.3.9 → 0.3.11

package/cli/mobile-doctor.mjs

@@ -208,6 +208,15 @@ async function doctorApp(app, flags, ctx) {
     else c.fail('site', 'Site API', `${url}/api/v1/site returned ${r.status}${r.json ? '' : ' (not the ACMS API)'}.`, { hint: 'Check EXPO_PUBLIC_ACMS_URL points at the site origin and the site runs @acms-subir/core with the mobile API.' });
   }
   const live = !!site;
+  // the site's own health (what Uptime Kuma watches): a warning, never a failure,
+  // since a local dev server usually has no scheduler running
+  if (live) {
+    const h = await getJson(`${url}/api/health`);
+    const bad = Object.entries(h.json?.checks ?? {}).filter(([, v]) => v !== 'ok' && v !== 'off').map(([k, v]) => `${k} ${v}`);
+    if (h.status === 200 && h.json?.status === 'ok') c.pass('health', 'Site health', 'Database, scheduler and email are working (/api/health).');
+    else if (h.status === 200 || h.status === 503) c.warn('health', 'Site health', `/api/health reports ${h.json?.status ?? 'down'}${bad.length ? `: ${bad.join(', ')}` : ''}.`, { hint: 'A stopped scheduler means no reminders, scheduled posts or emails: check the cron (Cloudflare) or the runner (Docker). Watch it with npx acms monitor kuma.' });
+    else c.warn('health', 'Site health', `/api/health returned ${h.status}.`, { hint: 'Update the site (npx acms update): older releases have no health check.' });
+  }
 
   // 6. app ids
   if (!appJson) c.fail('app-ids', 'App identity', 'app.json is missing or not valid JSON.', { hint: `Restore ${app.dir}/app.json (see the starter: npx acms add mobile --dry-run).` });

package/cli/monitor.mjs

@@ -0,0 +1,189 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomInt } from 'node:crypto';
+import { fail } from './common.mjs';
+import { listApps } from './mobile.mjs';
+
+// `acms monitor kuma`: puts a site's monitors into Uptime Kuma (website, app
+// API, staff app API, health, scheduler heartbeat) in one group, plus a
+// status page for Settings → Monitoring. Kuma has no REST API for this, so
+// it speaks Kuma's own dashboard protocol (Socket.IO over a WebSocket),
+// tested with Kuma 1.23 and 2.x. Running it again updates, never duplicates.
+// `--print` lists the same monitors to add by hand.
+// Login comes from KUMA_USERNAME / KUMA_PASSWORD (+ KUMA_TOTP for 2FA):
+// never arguments, never stored.
+
+const TIMEOUT = 15_000;
+
+/** the monitors for one site; `kuma` is the Kuma version major (1 or 2) */
+export function monitorPlan(site, opts = {}) {
+  const base = { method: 'GET', retryInterval: 60, resendInterval: 0, timeout: 30, ignoreTls: false, upsideDown: false, expiryNotification: false, maxredirects: 10, notificationIDList: {} };
+  const http = (name, path, extra = {}) => ({ ...base, type: 'http', name, url: `${site}${path}`, interval: 60, maxretries: 1, accepted_statuscodes: ['200-299'], ...extra });
+  const list = [
+    { key: 'website', what: 'The website answers', ...http('Website', '/') },
+    // the case to catch: the app API removed or broken (a 404 or a wrong answer)
+    { key: 'app-api', what: 'The app API answers as v1', ...http('App API', '/api/v1/site', { type: 'json-query', jsonPath: 'data.apiVersion', expectedValue: '1', ...(opts.kuma === 1 ? {} : { jsonPathOperator: '==' }) }) },
+    ...(opts.staff === false ? [] : [{ key: 'staff-api', what: 'The staff app API exists (401 = up)', ...http('Staff app API', '/api/v1/admin/me', { accepted_statuscodes: ['401'] }) }]),
+    { key: 'health', what: 'Database, scheduler and email (503 = down)', ...http('Health', '/api/health') },
+    { key: 'scheduler', what: 'The scheduler reported in the last 3 min', ...base, type: 'push', name: 'Scheduler', url: 'https://', interval: 180, maxretries: 0, accepted_statuscodes: ['200-299'], pushToken: opts.pushToken ?? token() },
+  ];
+  // Kuma 2 stores alert conditions; Kuma 1 refuses columns it doesn't have
+  return opts.kuma === 1 ? list : list.map((m) => ({ ...m, conditions: [] }));
+}
+function token(n = 32) {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  return Array.from({ length: n }, () => chars[randomInt(chars.length)]).join('');
+}
+
+// ---- a minimal Socket.IO v4 client (WebSocket transport only) -----------------
+
+export function kumaSocket(base) {
+  const url = `${base.replace(/^http/, 'ws')}/socket.io/?EIO=4&transport=websocket`;
+  const ws = new WebSocket(url);
+  const acks = new Map(), latest = {};
+  let next = 0, closed = false;
+  const ready = new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('timeout')), TIMEOUT);
+    ws.onerror = () => { clearTimeout(timer); reject(new Error('unreachable')); };
+    ws.onclose = () => { closed = true; for (const [, a] of acks) a.reject(new Error('closed')); acks.clear(); };
+    ws.onmessage = ({ data }) => {
+      const s = String(data);
+      if (s === '2') return ws.send('3'); // ping → pong
+      if (s.startsWith('0')) return ws.send('40'); // open → join the default namespace
+      if (s.startsWith('44')) { clearTimeout(timer); return reject(new Error('refused')); }
+      if (s.startsWith('40')) { clearTimeout(timer); return resolve(); }
+      const ack = /^43(\d+)([\s\S]*)$/.exec(s);
+      if (ack) { const a = acks.get(Number(ack[1])); acks.delete(Number(ack[1])); a?.resolve(JSON.parse(ack[2])[0]); return; }
+      if (s.startsWith('42')) { try { const [event, payload] = JSON.parse(s.slice(2)); latest[event] = payload; } catch { /* not ours */ } }
+    };
+  });
+  const call = (event, ...args) => new Promise((resolve, reject) => {
+    if (closed) return reject(new Error('closed'));
+    const id = next++;
+    const timer = setTimeout(() => { acks.delete(id); reject(new Error('timeout')); }, TIMEOUT);
+    acks.set(id, { resolve: (v) => { clearTimeout(timer); resolve(v); }, reject: (e) => { clearTimeout(timer); reject(e); } });
+    ws.send(`42${id}${JSON.stringify([event, ...args])}`);
+  });
+  /** waits until Kuma has pushed `event` (sent by the server after login), optionally one that passes `test` */
+  const wait = async (event, test = (v) => !!v, ms = 8000) => { for (let t = 0; t < ms && !test(latest[event]); t += 100) await new Promise((r) => setTimeout(r, 100)); return latest[event]; };
+  return { ready, call, wait, latest, close: () => { closed = true; ws.close(); } };
+}
+
+// ---- the command --------------------------------------------------------------
+
+function origin(raw, what) {
+  let u;
+  try { u = new URL(raw); } catch { fail('USAGE', `${what} must be an address like https://example.com.`); }
+  if (!['http:', 'https:'].includes(u.protocol) || u.username || u.password) fail('USAGE', `${what} must be an http(s) address without credentials.`);
+  return u.origin;
+}
+/** --url, else the site address baked into the mobile app (.env) */
+async function siteAddress(flags) {
+  if (flags.url) return origin(flags.url, '--url');
+  for (const app of await listApps().catch(() => [])) {
+    const env = await readFile(join(app.dir, '.env'), 'utf8').catch(() => '');
+    const v = env.match(/^EXPO_PUBLIC_ACMS_URL=(.*)$/m)?.[1]?.trim();
+    if (v && /^https:\/\//.test(v)) return origin(v, 'EXPO_PUBLIC_ACMS_URL');
+  }
+  fail('USAGE', 'Which site? Pass --url https://your-site.', [], ['acms monitor kuma --url https://your-site --kuma https://your-kuma']);
+}
+async function probe(url) {
+  try { const r = await fetch(url, { signal: AbortSignal.timeout(8000), headers: { accept: 'application/json' } }); return { status: r.status, json: await r.json().catch(() => null) }; }
+  catch { return { status: 0, json: null }; }
+}
+const slugFor = (host) => `acms-${host.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '').toLowerCase()}`.slice(0, 60);
+
+export async function monitorCommand(sub, flags) {
+  if (sub !== 'kuma') fail('USAGE', 'Use: acms monitor kuma --url https://your-site --kuma https://your-kuma [--print]');
+  const site = await siteAddress(flags);
+  const host = new URL(site).host;
+  // what the site has: staff app API (401) or not (404); the site name for labels
+  const [info, staff] = await Promise.all([probe(`${site}/api/v1/site`), probe(`${site}/api/v1/admin/me`)]);
+  const warnings = [];
+  if (info.status !== 200) warnings.push(`${site}/api/v1/site answered ${info.status || 'nothing'}: check the address (Kuma will show the App API as down until it answers).`);
+  const hasStaff = staff.status === 401;
+  if (!hasStaff) warnings.push('The staff app API isn’t on (no mobile.editor in the site config), so there is no Staff app API monitor.');
+  const group = info.json?.data?.name ? `${info.json.data.name} (${host})` : host;
+
+  const kumaRaw = flags.kuma ?? process.env.KUMA_URL;
+  if (flags.print || !kumaRaw) {
+    if (!flags.print) warnings.push('No --kuma address (or KUMA_URL): listing the monitors to add by hand.');
+    return { mode: 'print', site, group, monitors: monitorPlan(site, { staff: hasStaff }).map(view), warnings };
+  }
+  const kuma = origin(kumaRaw, '--kuma');
+  const username = process.env.KUMA_USERNAME, password = process.env.KUMA_PASSWORD;
+  if (!username || !password) fail('AUTH', 'Set KUMA_USERNAME and KUMA_PASSWORD (and KUMA_TOTP when Kuma uses two-factor sign-in).', [], ['read -rs KUMA_PASSWORD && export KUMA_PASSWORD   # keeps it out of shell history']);
+
+  const k = kumaSocket(kuma);
+  try {
+    try { await k.ready; } catch (e) { fail('NETWORK', `Couldn’t reach Uptime Kuma at ${kuma} (${e.message}).`, [], ['Check --kuma, or run with --print to add the monitors by hand.']); }
+    let login = await k.call('login', { username, password, token: process.env.KUMA_TOTP ?? '' });
+    if (login?.tokenRequired) fail('AUTH', 'Kuma asks for a two-factor code: set KUMA_TOTP to the current code and run again.');
+    if (!login?.ok) fail('AUTH', `Kuma refused the sign-in${login?.msg ? `: ${login.msg}` : ''}.`);
+    // the version only comes with the info Kuma sends after login
+    const info = await k.wait('info', (v) => !!v?.version);
+    const major = Number(String(info?.version ?? '2').split('.')[0]) || 2;
+    const existing = Object.values(await k.wait('monitorList') ?? {});
+    const ok = (r, what) => { if (!r?.ok) throw Object.assign(new Error(`${what}: ${r?.msg ?? 'no answer'}`), { kuma: true }); return r; };
+
+    // the group, then each monitor inside it (matched by name, so reruns update)
+    let parent = existing.find((m) => m.type === 'group' && m.name === group);
+    const results = [];
+    if (!parent) {
+      const { key: _k, what: _w, ...first } = monitorPlan(site, { kuma: major })[0];
+      const r = ok(await k.call('add', { ...first, type: 'group', name: group, url: 'https://', parent: null }), 'group');
+      parent = { id: r.monitorID };
+      results.push({ name: group, action: 'created', type: 'group' });
+    }
+    const children = existing.filter((m) => m.parent === parent.id);
+    const pushToken = children.find((m) => m.type === 'push' && m.name === 'Scheduler')?.pushToken;
+    const ids = [];
+    for (const { key: _k, what: _w, ...m } of monitorPlan(site, { kuma: major, staff: hasStaff, pushToken })) {
+      const old = children.find((c) => c.name === m.name);
+      const r = old
+        ? ok(await k.call('editMonitor', { ...old, ...m, id: old.id, parent: parent.id }), m.name)
+        : ok(await k.call('add', { ...m, parent: parent.id }), m.name);
+      ids.push(r.monitorID ?? old.id);
+      results.push({ name: m.name, action: old ? 'updated' : 'created', type: m.type, url: m.type === 'push' ? null : m.url });
+    }
+    const push = `${kuma}/api/push/${pushToken ?? (await k.call('getMonitor', ids[ids.length - 1]))?.monitor?.pushToken}`;
+
+    // a public status page with these monitors, for Settings → Monitoring
+    const slug = slugFor(host);
+    let page = await k.call('getStatusPage', slug);
+    if (!page?.ok) { ok(await k.call('addStatusPage', group, slug), 'status page'); page = await k.call('getStatusPage', slug); }
+    ok(page, 'status page');
+    ok(await k.call('saveStatusPage', slug, { ...page.config, title: group, published: true }, page.config.icon, [{ name: group, monitorList: ids.map((id) => ({ id })) }]), 'status page');
+
+    return { mode: 'kuma', site, kuma, kumaVersion: info?.version ?? null, group, monitors: results, pushUrl: push, statusPage: `${kuma}/status/${slug}`, warnings };
+  } catch (e) {
+    if (!e?.kuma) throw e;
+    // Kuma changed its dashboard protocol (or refused a field): fall back to the list
+    return { mode: 'print', site, group, monitors: monitorPlan(site, { staff: hasStaff }).map(view), warnings: [...warnings, `Kuma didn’t accept the setup (${e.message}). Add these by hand, or update ACMS.`] };
+  } finally { k.close(); }
+}
+
+const view = (m) => ({ name: m.name, type: m.type, url: m.type === 'push' ? null : m.url, interval: m.interval, check: m.what,
+  ...(m.jsonPath ? { jsonQuery: `${m.jsonPath} == ${m.expectedValue}` } : {}), acceptedStatusCodes: m.accepted_statuscodes, retries: m.maxretries });
+
+export function renderMonitor(d) {
+  const out = [];
+  for (const w of d.warnings) out.push(`! ${w}`);
+  if (d.mode === 'print') {
+    out.push(`Add these to Uptime Kuma in a group named "${d.group}":`, '');
+    for (const m of d.monitors) {
+      out.push(`  ${m.name}  (${m.type === 'json-query' ? 'HTTP(s) - Json Query' : m.type === 'push' ? 'Push' : 'HTTP(s)'}, every ${m.interval} s${m.retries ? `, ${m.retries} retry` : ''})`);
+      if (m.url) out.push(`    URL: ${m.url}`);
+      if (m.jsonQuery) out.push(`    Json Query: ${m.jsonQuery}`);
+      if (m.acceptedStatusCodes.join() !== '200-299') out.push(`    Accepted status codes: ${m.acceptedStatusCodes.join(', ')}`);
+      out.push(`    Checks: ${m.check}`);
+    }
+    out.push('', 'Then paste the Scheduler monitor’s push URL and a status page with these monitors into Admin → Settings → Monitoring.');
+    return out.join('\n');
+  }
+  out.push(`Uptime Kuma ${d.kumaVersion ?? ''} at ${d.kuma}: ${d.group}`);
+  for (const m of d.monitors) out.push(`  ✓ ${m.action.padEnd(7)} ${m.name}${m.url ? `  ${m.url}` : ''}`);
+  out.push('', 'Paste into Admin → Settings → Monitoring:', `  Scheduler heartbeat: ${d.pushUrl}`, `  Status page:         ${d.statusPage}`,
+    '', 'Alerts: in Kuma, add a notification (email, Telegram, Discord…) to the group’s monitors.');
+  return out.join('\n');
+}

package/cli/preview.mjs

@@ -17,7 +17,7 @@ export async function prepareFixture(p,dir,slug){
   await writeFile(join(root,'package.json'),JSON.stringify({name:'acms-isolated-preview',type:'module',private:true}));
   await writeFile(join(root,'astro.config.mjs'),`import {defineConfig,passthroughImageService} from 'astro/config';\nimport react from '@astrojs/react';\nimport node from '@astrojs/node';\nimport cloudflare from '@astrojs/cloudflare';\nimport acms from '@acms-subir/core';\nexport default defineConfig({output:'server',vite:{resolve:{preserveSymlinks:true}},integrations:[react(),acms({seed:{siteTitle:'Theme preview — synthetic content'}})],adapter:process.env.DEPLOY_TARGET==='cloudflare'?cloudflare({platformProxy:{enabled:false},imageService:'passthrough'}):node({mode:'standalone'}),image:{service:passthroughImageService()}});\n`);
   await writeFile(join(root,'src/pages/acms-theme-preview/setup.astro'),`---
-import {getRepo} from '@acms-subir/core/lib/repo/index';
+import {getRepo} from ${JSON.stringify(join(CORE,'src/lib/repo/index.ts'))};
 const repo=await getRepo(Astro.locals);
 let home=await repo.getPageBySlug('preview-home');
 if(!home){

package/deploy/Dockerfile

@@ -25,10 +25,14 @@ ENV NODE_ENV=production HOST=0.0.0.0 PORT=4321
 RUN npm install --no-save --no-audit --no-fund "@libsql/client@^0.15.0"
 COPY --from=build /app/dist ./dist
 COPY --from=build /app/node_modules/@acms-subir/core/email-runner.mjs ./email-runner.mjs
+# acms migrate: applies pending migrations under the database lock before
+# the server starts (the app's own first-request migration is the fallback)
+COPY --from=build /app/node_modules/@acms-subir/core/migrate.mjs ./acms/migrate.mjs
+COPY --from=build /app/node_modules/@acms-subir/core/cli/migrate.mjs /app/node_modules/@acms-subir/core/cli/migrations.generated.mjs ./acms/cli/
 # ./data holds the SQLite database and uploaded media — mount a volume here.
 # Only data/ needs to be writable (a chown -R of /app would copy-on-write
 # duplicate every node_modules file into a fresh layer)
 RUN mkdir -p data && chown node:node data
 USER node
 EXPOSE 4321
-CMD ["node", "./dist/server/entry.mjs"]
+CMD ["sh", "-c", "node ./acms/migrate.mjs && exec node ./dist/server/entry.mjs"]

package/deploy/compose.yml

@@ -14,8 +14,29 @@ services:
       - PORT=4321
       - ADMIN_PASSWORD=${ADMIN_PASSWORD:?set ADMIN_PASSWORD in .env}
       - SESSION_SECRET=${SESSION_SECRET:?set SESSION_SECRET in .env}
+      # Optional Clerk staff authentication (provider selected in astro.config).
+      - PUBLIC_CLERK_PUBLISHABLE_KEY=${PUBLIC_CLERK_PUBLISHABLE_KEY:-}
+      - CLERK_SECRET_KEY=${CLERK_SECRET_KEY:-}
+      - CLERK_AUTHORIZED_PARTIES=${CLERK_AUTHORIZED_PARTIES:-}
+      - CLERK_JWT_KEY=${CLERK_JWT_KEY:-}
+      - CLERK_OWNER_USER_ID=${CLERK_OWNER_USER_ID:-}
+      - CLERK_OWNER_LOCAL_USER_ID=${CLERK_OWNER_LOCAL_USER_ID:-}
       - EMAIL_RUNNER_SECRET=${EMAIL_RUNNER_SECRET:?set EMAIL_RUNNER_SECRET in .env}
       - EMAIL_ENCRYPTION_KEY=${EMAIL_ENCRYPTION_KEY:-}
+      # Optional: behind the Cloudflare proxy, clear its cache on every content
+      # change (token needs Zone → Cache Purge). See docs/caching.md.
+      - CLOUDFLARE_ZONE_ID=${CLOUDFLARE_ZONE_ID:-}
+      - CLOUDFLARE_API_TOKEN=${CLOUDFLARE_API_TOKEN:-}
+      # Optional scheduled off-site backups to S3-compatible storage (R2,
+      # Oracle Object Storage, AWS S3). See docs/production-deployment.md.
+      - BACKUP_S3_ENDPOINT=${BACKUP_S3_ENDPOINT:-}
+      - BACKUP_S3_BUCKET=${BACKUP_S3_BUCKET:-}
+      - BACKUP_S3_REGION=${BACKUP_S3_REGION:-}
+      - BACKUP_S3_ACCESS_KEY_ID=${BACKUP_S3_ACCESS_KEY_ID:-}
+      - BACKUP_S3_SECRET_ACCESS_KEY=${BACKUP_S3_SECRET_ACCESS_KEY:-}
+      - BACKUP_PREFIX=${BACKUP_PREFIX:-}
+      - BACKUP_KEEP=${BACKUP_KEEP:-}
+      - BACKUP_EVERY_HOURS=${BACKUP_EVERY_HOURS:-}
       - SQLITE_URL=file:./data/acms.db
     healthcheck:
       test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:4321/api/v1/content?limit=1').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]

package/docs/live-video.md

@@ -45,7 +45,7 @@ Rate-limit/quota errors back off. The UI reports estimated workload and provider
 - **Design → Pages:** add a **Live video** section; choose `card` or `player`, preview and publish using the existing design flow.
 - **Links:** add a **Live video** block and save. This is a compact card referencing the same site-wide status.
 - **Older widget pages:** add a **Live video** widget and choose its display mode. Rich-text-only/custom coded homepages must opt into a Design section or explicitly render the component.
-- **Custom themes:** import `LiveCard.astro` from `@acms-subir/core/components/LiveCard.astro`, or use the built-in `live` section. ACMS never injects a new placement automatically into a custom template. If a custom route renders the component, set `Astro.response.headers.set('Cache-Control', 'no-store')` in that route's frontmatter; the built-in page routes handle this for you.
+- **Custom themes:** import `LiveCard.astro` from `@acms-subir/core/theme/components/LiveCard.astro`, or use the built-in `live` section. ACMS never injects a new placement automatically into a custom template. If a custom route renders the component, set `Astro.response.headers.set('Cache-Control', 'no-store')` in that route's frontmatter; the built-in page routes handle this for you.
 
 ### How it looks
 

package/docs/mobile.md

@@ -113,11 +113,15 @@ Read the app's `AGENTS.md` too: it holds the same rules, next to the code.
 
 | Hook | For |
 | --- | --- |
-| `useSite()` | name, menu, languages, features (`calendar`, `bookings`, `blog`) |
+| `useSite()` | name, menu, languages, features (`calendar`, `bookings`, `blog`, `search`, `bookingChanges`, `guestSignIn`, `forms`, `links`) |
 | `usePage(slug)` | a published page: `mode` (`sections`/`content`), `sections`, `body.html`; 404 when missing |
-| `usePosts({ collection, limit })` / `usePost(slug)` | posts (infinite: `items`, `fetchNextPage`) |
+| `usePosts({ collection, limit, q })` / `usePost(slug)` | posts (infinite: `items`, `fetchNextPage`); `q` gives ranked search matches |
+| `useSearch(text, { types, collection, limit })` | site-wide search: `data.posts`, `data.pages`, `data.events` (each with `snippet.text` + `snippet.highlights`), `data.more`; debounced, blank text fetches nothing |
 | `useEvents({ calendar, from, to, limit, q })` | `data.occurrences[]` (`start`, `end`, `allDay`, `event`) in a window (default 30 days, max 90). `from`/`to` take a site-local day (`'2026-10-01'`) or an ISO date-time with a zone (`new Date().toISOString()`) |
 | `useEvent(slug)` | one event |
+| `useManagedBooking(token)` / `useCancelBooking` / `useRescheduleBooking` / `useRescheduleAvailability` | the booker's own booking (from `book()`'s `manageToken`): `can.cancel`, `can.reschedule`, `can.closed` (change cutoff passed: show "Contact us") |
+| `useGuest()` / `useMyBookings({ when })` | guest sign-in with an emailed code, then every booking made with that email; check `features.guestSignIn` |
+| `useLinks()` / `useForm(id)` / `useSubmitForm(id)` | the links page; published forms and sending answers; check `features.links` / `features.forms` |
 | `useResources()` / `useAvailability({ resource, link })` / `useBooking()` | bookings |
 | `useLocale()`, `useTheme()`, `useLayout()`, `useRefresh()`, `useOpenLink()` | language, tokens, layout, refresh, links |
 | `usePushRegistration({ topics })` / `usePushTopics()` / `useNotificationTaps()` | push notifications (see Push notifications) |
@@ -228,6 +232,23 @@ choose the calendar, better still: they add an **Upcoming events** section
 (its events source has a calendar and a limit) to the home page in the admin,
 and `<Sections>` renders it with no app code at all. Say so in your summary.
 
+**Search one collection as people type.** Check `useSite().data?.features.search`
+first; when it is false, hide the field. Pass a debounced value to `usePosts`:
+
+```tsx
+const [text, setText] = useState('');
+const q = useDebounced(text);
+const sermons = usePosts({ collection: 'sermons', q });
+// <TextInput value={text} onChangeText={setText} />, then sermons.items;
+// q && !sermons.isFetching && !sermons.items.length → "No sermons match"
+```
+
+For a search screen across everything, `useSearch(text)` returns groups
+(posts, pages, events) with snippets. Group `posts` by `collection` for
+headings, and when `more.posts` is true link to the collection list with that
+`q`. Search matches the main-language text, so Spanish words find content only
+where the original is Spanish.
+
 **A native version of a coded section.** From the site folder:
 `npx acms section new visit-banner --theme <slug>` (new) or, for an existing
 coded section, write `mobile/sections/VisitBanner.tsx` typed with

package/docs/theme-authoring.md

@@ -91,6 +91,12 @@ The theme API version covers documented template/section contracts and public co
 
 `theme diff` compares against the creation snapshot; `--baseline <folder>` selects another version. Runtime settings/navigation differences are available in `design pull`.
 
+## Moving a theme between sites or machines
+
+Design → **Export** downloads the design as the Design screen shows it (draft over live) as one `<slug>-<date>.acms-theme.zip`: `manifest.json` (format `acms-theme` v1, theme slug/name/version, core version), `design.json` (token overrides, logo/dark logo/favicon/cover, section layouts keyed by page slug, link targets by URL, and navigation only when ticked) and `media/<key>` with `media.json` for the images it uses. It never contains posts, page text, keys or other settings. Design → **Import** previews the file against the receiving site, uploads its images (kept by id, so `/media/` URLs stay valid), and stages everything as a draft; publish it from Review as usual. Layouts land on the page with the same slug (the exported home page falls back to this site's home); pages with no match are reported and skipped. Section links follow the item at the same URL, otherwise keep their typed address. Owners only; editors cannot export or import.
+
+Theme **code** is not in the file: it is compiled into the build. When the file names a theme this site lacks, the import keeps the current theme and says so. Move `src/themes/<slug>/` with git, or `acms theme pack` / `acms theme install`, then rebuild. The same endpoints are scriptable with a scoped key: `GET /api/design/export` (`design:read`, plus `media:read` unless `?media=0`; `?nav=1` adds menus) and `POST /api/design/import` with `{ revision, design, nav?, dryRun? }` (`design:write-draft`).
+
 ## Sharing, versions and rollback
 
 `theme pack` produces a deterministic theme-only tgz. `theme install` validates the archive before writing, rejects traversal/links/unexpected files/incompatible core versions, and never runs install scripts. Use `--force` for intentional replacement: the previous directory is retained in `.acms/theme-backups/`. `.acms/themes.lock.json` records the pinned version, digest and backup path. Copy a retained backup to a new theme identity or re-pack/install it to roll code back; rebuild and redeploy. No automatic download of theme dependencies occurs.

package/integration.mjs

@@ -71,6 +71,8 @@ const ROUTES = [
   ['/api/email/webhooks/[provider]', 'api/email/webhooks/[provider].ts'],
   ['/api/email/run', 'api/email/run.ts'],
   ['/api/ops/status', 'api/ops/status.ts'],
+  ['/api/health', 'api/health.ts'],
+  ['/api/monitoring', 'api/monitoring.ts'],
   ['/admin/ai', 'admin/ai.astro'],
   ['/admin/import', 'admin/import.astro'],
   ['/admin/tags', 'admin/tags.astro'],
@@ -86,6 +88,8 @@ const ROUTES = [
   ['/api/design/keys', 'api/design/keys.ts'],
   ['/api/design/capabilities', 'api/design/capabilities.ts'],
   ['/api/design/media', 'api/design/media.ts'],
+  ['/api/design/export', 'api/design/export.ts'],
+  ['/api/design/import', 'api/design/import.ts'],
   ['/api/design/ai', 'api/design/ai.ts'],
   ['/api/design/translate', 'api/design/translate.ts'],
   ['/api/agent', 'api/agent/index.ts'],
@@ -231,8 +235,30 @@ function resolveI18n(i18n, contentBases) {
 }
 
 // Defaults + validation for acms({ search }). Search ships on; disabling it
-// removes the /search page(s) and /api/search from the route table, and the
+// removes the /search page(s), /api/search and /api/v1/search from the route table, and the
 // layout skips the header trigger + modal (lib/search-config.ts).
+// acms({ cache }): CDN caching of public pages and the public app API.
+// `false` turns it off (every response is private, no-store); `memory` is the
+// Node-only in-process cache of public API data, keyed by content version.
+function resolveCache(cache) {
+  const defaults = { enabled: true, maxAge: 60, staleWhileRevalidate: 86400, memory: true };
+  if (cache === undefined || cache === true) return defaults;
+  if (cache === false) return { ...defaults, enabled: false, memory: false };
+  if (!cache || typeof cache !== 'object' || Array.isArray(cache)) throw new Error('acms: cache must be false or { maxAge?, staleWhileRevalidate?, memory? }');
+  const unknown = Object.keys(cache).filter((k) => !['maxAge', 'staleWhileRevalidate', 'memory'].includes(k));
+  if (unknown.length > 0) {
+    throw new Error(`acms: unknown cache key${unknown.length > 1 ? 's' : ''} ${unknown.map((k) => `"${k}"`).join(', ')} — valid keys are maxAge, staleWhileRevalidate and memory`);
+  }
+  const out = { ...defaults, ...cache };
+  for (const k of ['maxAge', 'staleWhileRevalidate']) {
+    if (!Number.isInteger(out[k]) || out[k] < 0 || out[k] > 31_536_000) throw new Error(`acms: cache.${k} must be a whole number of seconds (0–31536000)`);
+  }
+  if (typeof out.memory !== 'boolean') throw new Error('acms: cache.memory must be true or false');
+  // maxAge 0 means "don't let the CDN store anything" — same as cache: false
+  if (out.maxAge === 0) return { ...out, enabled: false };
+  return out;
+}
+
 function resolveSearch(search) {
   if (search === undefined) return { enabled: true };
   const unknown = Object.keys(search).filter((k) => k !== 'enabled');
@@ -471,7 +497,8 @@ function acmsVitePlugin(userConfig) {
  *   browser (/admin/app-auth, OAuth 2.0 + PKCE; only the listed redirect URIs
  *   receive codes) and edit through the bearer-token /api/v1/admin/* API.
  * @param {{enabled?: boolean}} [options.search]
- *   Public site search: the /search page, the /api/search JSON endpoint, and
+ *   Public site search: the /search page, the /api/search JSON endpoint, app
+ *   search (/api/v1/search and /api/v1/content?q=), and
  *   the header search modal. On by default — set `enabled: false` to remove
  *   all three.
  * @param {false | {enabled?: boolean, base?: string, eventsBase?: string, defaultView?: 'month' | 'week' | 'list', eventFields?: Array<{key: string, label?: string, type?: 'text' | 'textarea' | 'number' | 'url' | 'select', options?: string[]}>}} [options.calendar]
@@ -490,6 +517,15 @@ function acmsVitePlugin(userConfig) {
  *   pasted map links still work.
  * @param {false | {enabled?: boolean, operatorName?: string, contactEmail?: string, updatedAt?: string}} [options.legal]
  *   Default privacy/terms routes and footer links; published CMS pages at those slugs override the text.
+ * @param {{provider?: 'builtin' | 'clerk'}} [options.auth] Staff authentication provider. Defaults to builtin.
+ * @param {false | {maxAge?: number, staleWhileRevalidate?: number, memory?: boolean}} [options.cache]
+ *   Shared caching of public pages and the public app API (`/api/v1/*`):
+ *   `Cache-Control: public, s-maxage=<maxAge>, stale-while-revalidate=<staleWhileRevalidate>`
+ *   (defaults 60 and 86400). Admin, previews, signed-in visitors, bookings,
+ *   forms and every non-GET request stay `private, no-store`. Every content
+ *   change clears the cache (Workers Cache, or the Cloudflare zone when
+ *   CLOUDFLARE_ZONE_ID + CLOUDFLARE_API_TOKEN are set). `memory: false` turns
+ *   off the Node in-process API cache. `cache: false` turns all of it off.
  * @returns {import('astro').AstroIntegration}
  */
 export default function acms(options = {}) {
@@ -500,6 +536,7 @@ export default function acms(options = {}) {
   ]);
   const i18n = resolveI18n(options.i18n, contentBases);
   const search = resolveSearch(options.search);
+  const cache = resolveCache(options.cache);
   const mobile = resolveMobile(options.mobile);
   const calendar = resolveCalendar(options.calendar, contentBases, i18n.locales);
   const maps = resolveMaps(options.maps);
@@ -507,13 +544,18 @@ export default function acms(options = {}) {
   if (typeof legal.enabled !== 'boolean' || ['operatorName','contactEmail','updatedAt'].some(k => typeof legal[k] !== 'string')) throw new Error('acms: invalid legal configuration');
   if (legal.contactEmail && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(legal.contactEmail)) throw new Error('acms: legal.contactEmail must be an email address');
   if (legal.updatedAt && (!/^\d{4}-\d{2}-\d{2}$/.test(legal.updatedAt) || !Number.isFinite(Date.parse(legal.updatedAt)) || new Date(legal.updatedAt).toISOString().slice(0,10) !== legal.updatedAt)) throw new Error('acms: legal.updatedAt must be a valid YYYY-MM-DD date');
+  const auth = { provider: options.auth?.provider === undefined ? 'builtin' : options.auth.provider };
+  if (options.auth !== undefined && (!options.auth || typeof options.auth !== 'object' || Array.isArray(options.auth) || Object.keys(options.auth).some(k => k !== 'provider'))) throw new Error('acms: auth accepts only provider');
+  if (!['builtin', 'clerk'].includes(auth.provider)) throw new Error('acms: auth.provider must be builtin or clerk');
   const userConfig = {
+    auth,
     coreVersion: CORE_VERSION,
     brand: options.brand ?? {},
     seed: options.seed ?? {},
     content,
     i18n,
     search,
+    cache,
     mobile,
     calendar,
     maps,
@@ -532,6 +574,9 @@ export default function acms(options = {}) {
     ['/api/v1/openapi.json', 'api/v1/openapi.json.ts'],
     ['/api/v1/content', 'api/v1/content/index.ts'],
     ['/api/v1/content/[id]', 'api/v1/content/[id].ts'],
+    ['/api/v1/links', 'api/v1/links.ts'],
+    ['/api/v1/forms/[id]', 'api/v1/forms/[id]/index.ts'],
+    ['/api/v1/forms/[id]/responses', 'api/v1/forms/[id]/responses.ts'],
   ];
   if (mobile.ios) routes.push(['/.well-known/apple-app-site-association', '.well-known/apple-app-site-association.ts']);
   if (mobile.android) routes.push(['/.well-known/assetlinks.json', '.well-known/assetlinks.json.ts']);
@@ -541,9 +586,10 @@ export default function acms(options = {}) {
       ['/api/v1/devices/[token]', 'api/v1/devices/[token].ts'],
       ['/api/v1/push/topics', 'api/v1/push/topics.ts'],
       ['/api/push/admin', 'api/push/admin.ts'],
-      ['/admin/mobile', 'admin/mobile.astro'],
     );
   }
+  // Admin → Mobile app: app access switches always; notifications when push is on
+  routes.push(['/admin/mobile', 'admin/mobile.astro'], ['/api/mobile/access', 'api/mobile/access.ts']);
   if (mobile.editor.enabled) {
     // editor apps: browser sign-in (OAuth 2.0 + PKCE) and the bearer-only admin API
     routes.push(
@@ -564,6 +610,19 @@ export default function acms(options = {}) {
       ['/api/v1/admin/media', 'api/v1/admin/media/index.ts'],
       ['/api/v1/admin/bookings', 'api/v1/admin/bookings/index.ts'],
       ['/api/v1/admin/bookings/[id]/[action]', 'api/v1/admin/bookings/[id]/[action].ts'],
+      // schedule + setup (calendar/booking handlers answer 404 when those modules are off)
+      ['/api/v1/admin/schedule', 'api/v1/admin/schedule.ts'],
+      ['/api/v1/admin/resources', 'api/v1/admin/resources/index.ts'],
+      ['/api/v1/admin/resources/[id]', 'api/v1/admin/resources/[id]/index.ts'],
+      ['/api/v1/admin/resources/[id]/links', 'api/v1/admin/resources/[id]/links/index.ts'],
+      ['/api/v1/admin/resources/[id]/links/[linkId]', 'api/v1/admin/resources/[id]/links/[linkId].ts'],
+      ['/api/v1/admin/resources/[id]/blocks', 'api/v1/admin/resources/[id]/blocks/index.ts'],
+      ['/api/v1/admin/resources/[id]/blocks/[blockId]', 'api/v1/admin/resources/[id]/blocks/[blockId].ts'],
+      ['/api/v1/admin/calendars', 'api/v1/admin/calendars/index.ts'],
+      ['/api/v1/admin/calendars/[id]', 'api/v1/admin/calendars/[id].ts'],
+      ['/api/v1/admin/forms', 'api/v1/admin/forms/index.ts'],
+      ['/api/v1/admin/forms/[id]/responses', 'api/v1/admin/forms/[id]/responses.ts'],
+      ['/api/v1/admin/links', 'api/v1/admin/links.ts'],
     );
   }
   if (legal.enabled) routes.push(['/privacy', 'legal/privacy.astro'], ['/terms', 'legal/terms.astro']);
@@ -577,7 +636,7 @@ export default function acms(options = {}) {
     if (l !== i18n.defaultLocale) routes.push([`/${l}`, 'index.astro']);
   }
   if (search.enabled) {
-    routes.push(['/search', 'search.astro'], ['/api/search', 'api/search.ts']);
+    routes.push(['/search', 'search.astro'], ['/api/search', 'api/search.ts'], ['/api/v1/search', 'api/v1/search.ts']);
     // a locale-prefixed search page per non-default locale, mirroring the
     // per-locale home routes; search.astro derives its locale from the path
     for (const l of i18n.locales) {
@@ -604,6 +663,17 @@ export default function acms(options = {}) {
       ['/admin/calendar/integrations', 'admin/calendar/integrations.astro'],
       ['/api/calendar/docs', 'api/calendar/docs.ts'],
       [`${calendar.bookBase}/manage/[token]`, 'book/manage/[token].astro'],
+      // the booker's own booking from an app (token in the Booking-Token header)
+      ['/api/v1/bookings/manage', 'api/v1/bookings/manage/index.ts'],
+      ['/api/v1/bookings/manage/cancel', 'api/v1/bookings/manage/cancel.ts'],
+      ['/api/v1/bookings/manage/availability', 'api/v1/bookings/manage/availability.ts'],
+      ['/api/v1/bookings/manage/reschedule', 'api/v1/bookings/manage/reschedule.ts'],
+      ['/api/v1/bookings/manage/ics', 'api/v1/bookings/manage/ics.ts'],
+      // guest sign-in for "My bookings" (answers 404 until email is set up)
+      ['/api/v1/guest/code', 'api/v1/guest/code.ts'],
+      ['/api/v1/guest/token', 'api/v1/guest/token.ts'],
+      ['/api/v1/guest/bookings', 'api/v1/guest/bookings.ts'],
+      ['/api/v1/guest/revoke', 'api/v1/guest/revoke.ts'],
       ['/admin/calendar/bookings', 'admin/calendar/bookings.astro'],
     );
     if (calendar.bookings) {

package/migrate.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// acms-migrate: apply pending schema migrations under the database lock.
+// The Docker image runs this before the server; see cli/migrate.mjs.
+import { main } from './cli/migrate.mjs';
+await main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "publishConfig": {
     "access": "public"
   },
@@ -24,22 +24,16 @@
   "bin": {
     "acms": "cli.mjs",
     "acms-email-runner": "email-runner.mjs",
-    "acms-check-deployment": "ops-check.mjs"
+    "acms-check-deployment": "ops-check.mjs",
+    "acms-migrate": "migrate.mjs"
   },
   "exports": {
     ".": "./integration.mjs",
     "./package.json": "./package.json",
     "./actions": "./src/actions/index.ts",
-    "./middleware": "./src/middleware.ts",
-    "./worker": "./src/worker.ts",
-    "./lib/*": "./src/lib/*",
-    "./pages/*": "./src/pages/*",
-    "./components/*": "./src/components/*",
-    "./layouts/*": "./src/layouts/*",
-    "./styles/*": "./src/styles/*",
-    "./themes/*": "./src/themes/*",
     "./theme": "./src/theme-sdk/index.ts",
     "./theme/schema": "./src/theme-sdk/contract.mjs",
+    "./theme/components/LiveCard.astro": "./src/components/LiveCard.astro",
     "./theme/components/*": "./src/components/site/*"
   },
   "files": [
@@ -50,12 +44,14 @@
     "email-runner.mjs",
     "deploy",
     "ops-check.mjs",
+    "migrate.mjs",
     "cli",
     "docs",
     "section-library",
     "mobile-template"
   ],
   "dependencies": {
+    "@clerk/backend": "^3.22.0",
     "@cloudflare/workers-types": "^5.20260927.1",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
@@ -109,10 +105,12 @@
     "@types/react-dom": "^19.2.4",
     "@types/sanitize-html": "^2.16.1",
     "@types/turndown": "^5.0.6",
+    "esbuild": "^0.28.1",
     "miniflare": "^5.20260801.0-alpha",
     "vitest": "^3.2.0"
   },
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "gen:migrations": "node scripts/gen-migrations.mjs"
   }
 }