@acms-subir/core 0.1.0 → 0.3.0

package/docs/theme-authoring.md

@@ -0,0 +1,103 @@
+# ACMS theme authoring contract (API 1)
+
+Use the installed version as the authority: `acms inspect --json`, `acms schema theme --json`, and `acms docs theme --format markdown`. `astro sync`, dev or build writes a non-secret configuration inventory used by inspect. Never copy credentials or site content into a theme package.
+
+## Start and validate
+
+```sh
+acms theme create studio --from business
+acms theme dev studio
+acms theme check studio --build --json
+acms theme diff studio
+acms theme pack studio
+```
+
+The business starter includes a typed custom Statement section to adapt. Editorial is another starter: `--from editorial`. An installed project theme can also be used as a starter. Create never overwrites an existing folder. `agent init` writes `.agents/skills/acms-theme/SKILL.md` without modifying your existing instruction files.
+
+Themes live in `src/themes/<slug>/` with `theme.json`, optional `theme.css`, `templates/`, `sections/`, and `assets/`. Metadata supports name, slug, semantic version, apiVersion (1), core compatibility range, description, author, license, token defaults, post defaults, templates, section definitions and asset inventory. Legacy manifests without version metadata receive defaults. Do not include package scripts or dependencies in theme archives.
+
+The token schema is shared with the runtime, not a separate CLI copy. Color schemes, typography, spacing, width, shape and header/footer defaults are presentation. Site title, page copy, image choices and section order belong to the owner in ACMS. New theme files require build/deployment; database-only edits to installed sections and brand overrides do not.
+
+## Public imports and template props
+
+```astro
+---
+import type { HomeProps } from '@acms-subir/core/theme';
+import { collectionUrl } from '@acms-subir/core/theme';
+import PostCard from '@acms-subir/core/theme/components/PostCard.astro';
+interface Props extends HomeProps {}
+const { page, posts } = Astro.props;
+---
+{page?.bodyHtml && <div set:html={page.bodyHtml} />}
+{posts.map(post => <PostCard href={collectionUrl(post.collection, post.slug)} title={post.title} excerpt={post.excerpt} />)}
+```
+
+Public types: HomeProps (settings, page, posts, tags), PageProps (settings, page, html), PostProps (settings, post, html, authors, related), EventProps (settings, event, occurrence, calendars, html, upcoming, origin, preview, rsvp), SectionProps (settings, page, variant, data). Public components: PostCard with card/row/feature variants, Pager with base/page/count, TagLabel with name/href/accent. Helpers include collectionUrl, postUrl, postsIndexUrl, tagUrl, formatDate, slugify, authorSlug, localeFromPath, localeHomeUrl and CONTENT. Use collectionUrl for non-default collections; postUrl is the built-in posts alias.
+
+Template filenames: `home.astro`, `event.astro`, `post-<name>.astro`, `page-<name>.astro`. Post/page variants are selected in the content editor. Core owns routes, auth, SEO and published-content queries. Templates only replace their documented content area. Never query private data from a public section or insert untrusted strings with set:html. The core's rendered `html`/`bodyHtml` is the intended rich-content handoff.
+
+## Editable sections
+
+Every theme gets Hero, Features, Testimonials, FAQ, Posts, CTA and Existing page content. The last section explicitly adapts the original page renderer: published rich text and widgets can appear among your sections, with their editing lifecycle unchanged. In Design → Pages, select a page, enable Sections, add/reorder/duplicate/hide sections, edit fields and save the section draft. Review and publish through the existing Design workflow. Page content stays intact; switching back to Page content restores the existing renderer without deleting section data. Unknown sections and schema-version mismatches retain their data, show an editor warning and block publication until hidden, removed or migrated.
+
+Custom definitions live in `theme.json`:
+
+```json
+{
+  "name": "Studio", "slug": "studio", "version": "1.0.0", "apiVersion": 1,
+  "core": ">=0.2.0 <1.0.0",
+  "sections": {
+    "statement": {
+      "name": "Statement", "version": 1,
+      "component": "sections/Statement.astro", "variants": ["default"],
+      "fields": { "heading": { "label": "Heading", "type": "text", "default": "Welcome" } }
+    }
+  }
+}
+```
+
+The component receives SectionProps. Supported field kinds: text, textarea, image, url, select (options required), number. Instances have stable id/type/version/variant/hidden/data fields. A page layout has mode and sections, persisted by page ID in `settings.sectionPages`. Section values and order have a design draft lifecycle distinct from rich-text/widget page drafts; publishing design does not publish pending page text. Theme switches preserve the map. To migrate a custom schema, transform a pulled draft to the new version, review it, and push it with its revision; incompatible versions never auto-convert silently. Existing widget pages continue using their original renderer.
+
+Images in template files should be imported using relative paths so Astro bundles them. Theme CSS can reference `url(assets/name.webp)`; ACMS resolves it through the bundled asset inventory. Brand images and editable section images use the media library. Packaged assets must be local files under assets; declare them in the manifest. Use `theme pack --optimize` to run current img-subir and rewrite references before packing. Original-image backup directories are excluded.
+
+## Styling compatibility
+
+The theme API version covers documented template/section contracts and public components. CSS variables emitted from the token schema are the supported customization surface. Arbitrary internal DOM selectors are not a stable API. Public theme v2 changed `.site-header-in`, `.site-tools`, and the position of share buttons in the byline. `header: minimal` is the closest old-header behavior. Legacy token JSON loading does not guarantee old CSS matches new markup. Recheck custom selectors after a core upgrade.
+
+## Local previews and checks
+
+`theme dev` starts a loopback Astro server in a new `.acms/previews/` workspace, with an isolated SQLite database, generated local secrets and linked theme sources for live reload. Interactive terminal sessions open `/acms-theme-preview` automatically; otherwise open the printed URL. Initialize synthetic content from its controls. It includes home/page/post/event, archive pagination, long titles, missing covers, calendar, search and 404; empty booking surfaces remain empty. Use the fixture device and scheme controls. No production config or credentials are copied. Theme code is application code and runs in your local process; only run themes you trust. Stop with Ctrl-C. Remove old preview folders when no longer needed.
+
+`theme check` validates the manifest, compatibility range, declared files, supported file types, imports and asset references, and reports token contrast estimates. `--build` compiles an isolated consumer with both Node and Cloudflare adapters. Contrast results are not an accessibility certification; review actual custom templates at narrow/wide viewports, keyboard focus and light/dark palettes. A browser-only hover or interaction cannot be proven by a build.
+
+`theme diff` compares against the creation snapshot; `--baseline <folder>` selects another version. Runtime settings/navigation differences are available in `design pull`.
+
+## 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.
+
+Deploy new code under a distinct theme identity before selecting it. Editing the active theme's deployed CSS/templates changes live presentation regardless of a settings draft. Design history stores the last 20 outgoing settings/navigation/section snapshots, not asset bytes or compiled code. Restoring a history version stages a draft; publish is separate. Old snapshots without section fields preserve current layouts.
+
+## Remote operations
+
+Owners create scoped credentials under Design → Access. A key has design:read, design:write-draft, design:publish, media:read and/or media:write. Publish is off by default. Legacy content-agent keys retain content access only and cannot access the design API. The read-only `/api/design/capabilities` probe accepts any explicit design/media scope, so a media-only profile can connect without gaining design read access.
+
+```sh
+# Set ACMS_TOKEN using your shell/secret manager; do not put it in command arguments.
+acms site connect https://your-site.example --site production
+acms design pull --site production --output draft.json
+# Edit patch values in draft.json; keep its revision.
+acms design push --site production --draft --file draft.json
+acms design pull --site production
+acms design publish --site production --revision 12
+acms design history --site production
+acms design rollback VERSION_ID --site production --revision 13
+```
+
+Use the actual revision returned by your site, not the illustrative numbers above. All remote design writes compare revisions; conflict exits 4 instead of clobbering another editor. Restore and push only stage drafts. Share/revoke require draft-write scope and a revision; reviewer URLs grant no mutation permission and do not reveal unpublished content. Treat a share URL as a credential.
+
+Profiles under `~/.config/acms/sites.json` store only URL and token environment-variable name, with restricted permissions. Set ACMS_CONFIG_DIR for an alternate location. Use `--token-env VARIABLE` to choose another token. Tokens are read at invocation and are never written into a project, logs or profile. HTTPS is required except loopback development sites.
+
+`content capabilities` discovers the existing content-agent schema; content list/get/create/update/publish use its existing key and API contract with JSON arguments from --file or stdin. Connect a separate profile/token variable when content and design use separate credentials. `media list` and `media upload <image>` use explicit media scopes. Upload runs current img-subir before sending the resulting PNG/JPEG/WebP/GIF; the API caps images at 10 MB. No automatic retry of writes after ambiguous network failure.
+
+Every command accepts --json and --help. JSON uses schema acms.cli/1 with ok/data or code/message/details/hints. stdout carries only the result; progress goes to stderr. --dry-run previews mutations. --cwd selects a project. --yes never expands permissions or bypasses compatibility. Exit codes: 0 success, 1 maintenance/check signal, 2 usage/validation, 3 auth, 4 conflict, 5 network/server failure.

package/email-runner.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// Independent Node scheduler: reminders must not depend on page visitors.
+import { setTimeout as sleep } from 'node:timers/promises';
+import { writeFile } from 'node:fs/promises';
+const base = process.env.EMAIL_RUNNER_URL || process.env.SITE_URL;
+const secret = process.env.EMAIL_RUNNER_SECRET;
+if (!base || !secret || secret.length < 32) {
+  console.error('Set EMAIL_RUNNER_URL (site origin) and a 32+ character EMAIL_RUNNER_SECRET.');
+  process.exit(1);
+}
+const url = new URL('/api/email/run', base);
+if (url.protocol !== 'https:' && !['localhost','127.0.0.1','[::1]'].includes(url.hostname)) {
+  console.error('The runner requires HTTPS outside localhost.'); process.exit(1);
+}
+const controller = new AbortController();
+let stopping = false;
+process.on('SIGINT', () => { stopping = true; controller.abort(); });
+process.on('SIGTERM', () => { stopping = true; controller.abort(); });
+do {
+  const started = Date.now();
+  try {
+    const result = await fetch(url, { method: 'POST', headers: { authorization: `Bearer ${secret}`, 'Content-Type': 'application/json', Origin: url.origin }, signal: AbortSignal.any([AbortSignal.timeout(150000), controller.signal]), redirect: 'error' });
+    await result.body?.cancel();
+    if (!result.ok) throw new Error(`Runner endpoint returned HTTP ${result.status}`);
+    if (process.env.SCHEDULER_HEARTBEAT_FILE) await writeFile(process.env.SCHEDULER_HEARTBEAT_FILE, String(Date.now()));
+  } catch (error) {
+    console.error(new Date().toISOString(), error instanceof Error ? error.message : 'Email runner failed');
+    if (process.argv.includes('--once')) process.exitCode = 1;
+  }
+  if (stopping || process.argv.includes('--once')) break;
+  await sleep(Math.max(1000, 60000 - (Date.now() - started)), undefined, { signal: controller.signal }).catch(() => {});
+} while (!stopping);

package/integration.mjs

@@ -25,6 +25,7 @@ export const workerEntrypoint = entry('./src/worker.ts');
 const ROUTES = [
   // public site (post + tag routes are built from config in acms() below)
   ['/', 'index.astro'],
+  ['/404', '404.astro'],
   ['/[...slug]', '[...slug].astro'],
   ['/author/[slug]', 'author/[slug].astro'],
   ['/links', 'links.astro'],
@@ -53,11 +54,29 @@ const ROUTES = [
   ['/admin/posts', 'admin/posts/index.astro'],
   ['/admin/posts/[id]', 'admin/posts/[id].astro'],
   ['/admin/settings', 'admin/settings.astro'],
+  ['/admin/email', 'admin/email.astro'],
+  ['/account/[action]', 'account/[action].astro'],
+  ['/api/email/settings', 'api/email/settings.ts'],
+  ['/api/email/webhooks/[provider]', 'api/email/webhooks/[provider].ts'],
+  ['/api/email/run', 'api/email/run.ts'],
+  ['/api/ops/status', 'api/ops/status.ts'],
+  ['/admin/ai', 'admin/ai.astro'],
   ['/admin/tags', 'admin/tags.astro'],
   ['/admin/users', 'admin/users.astro'],
   // API
   ['/api/backup', 'api/backup.ts'],
   ['/api/drafts', 'api/drafts.ts'],
+  ['/api/ai/settings', 'api/ai/settings.ts'],
+  ['/api/ai/test', 'api/ai/test.ts'],
+  ['/api/ai/clean', 'api/ai/clean.ts'],
+  ['/api/ai/draft', 'api/ai/draft.ts'],
+  ['/api/design', 'api/design/index.ts'],
+  ['/api/design/keys', 'api/design/keys.ts'],
+  ['/api/design/capabilities', 'api/design/capabilities.ts'],
+  ['/api/design/media', 'api/design/media.ts'],
+  ['/api/agent', 'api/agent/index.ts'],
+  ['/api/agent/docs', 'api/agent/docs.ts'],
+  ['/api/mcp', 'api/mcp.ts'],
   ['/api/media/upload', 'api/media/upload.ts'],
   ['/api/restore', 'api/restore.ts'],
 ];
@@ -65,7 +84,7 @@ const ROUTES = [
 // First segments of the fixed routes above — a configured base landing on one
 // of these would shadow a real page, so it's a build-time error.
 const RESERVED_BASES = new Set([
-  '/admin', '/api', '/author', '/embed', '/go', '/links', '/media', '/preview', '/search',
+  '/admin', '/api', '/author', '/embed', '/go', '/links', '/media', '/preview', '/search', '/privacy', '/terms',
 ]);
 
 // Collection keys that would collide with admin sections or read ambiguously.
@@ -199,6 +218,97 @@ function resolveSearch(search) {
   return { enabled };
 }
 
+// Defaults + validation for acms({ calendar }). The calendar module ships on:
+// a main calendar page at `base`, event pages under `eventsBase`, ICS feeds,
+// and the admin Calendar section. `calendar: false` (or enabled: false)
+// removes every calendar route and hides the admin section; events stay in
+// the database. Bases follow the same rules as collection bases.
+const EVENT_FIELD_TYPES = ['text', 'textarea', 'number', 'url', 'select'];
+function resolveCalendar(calendar, contentBases, locales) {
+  const defaults = {
+    enabled: true, base: '/calendar', eventsBase: '/events', bookings: true, bookBase: '/book',
+    resourceKinds: ['Room', 'Person', 'Vehicle', 'Equipment'], defaultView: 'month', eventFields: [],
+  };
+  if (calendar === false) return { ...defaults, enabled: false };
+  if (calendar === undefined || calendar === true) calendar = {};
+  if (typeof calendar !== 'object' || calendar === null || Array.isArray(calendar)) {
+    throw new Error('acms: calendar must be an object (or false to disable the calendar module)');
+  }
+  const known = ['enabled', 'base', 'eventsBase', 'bookings', 'bookBase', 'resourceKinds', 'defaultView', 'eventFields'];
+  const unknown = Object.keys(calendar).filter((k) => !known.includes(k));
+  if (unknown.length > 0) {
+    throw new Error(
+      `acms: unknown calendar key${unknown.length > 1 ? 's' : ''} ${unknown.map((k) => `"${k}"`).join(', ')} — ` +
+        `valid keys are ${known.map((k) => `calendar.${k}`).join(', ')}`
+    );
+  }
+  const enabled = calendar.enabled ?? true;
+  if (typeof enabled !== 'boolean') throw new Error('acms: calendar.enabled must be true or false');
+  const resolved = {
+    enabled,
+    base: calendar.base ?? defaults.base,
+    eventsBase: calendar.eventsBase ?? defaults.eventsBase,
+    bookings: calendar.bookings ?? true,
+    bookBase: calendar.bookBase ?? defaults.bookBase,
+    resourceKinds: calendar.resourceKinds ?? defaults.resourceKinds,
+    defaultView: calendar.defaultView ?? defaults.defaultView,
+    eventFields: [],
+  };
+  if (typeof resolved.bookings !== 'boolean') throw new Error('acms: calendar.bookings must be true or false');
+  if (!Array.isArray(resolved.resourceKinds) || !resolved.resourceKinds.length || resolved.resourceKinds.some((k) => typeof k !== 'string' || !k.trim())) {
+    throw new Error('acms: calendar.resourceKinds must be a non-empty array of labels, e.g. ["Room", "Person"]');
+  }
+  if (!['month', 'week', 'list'].includes(resolved.defaultView)) {
+    throw new Error(`acms: calendar.defaultView must be "month", "week", or "list" — got "${resolved.defaultView}"`);
+  }
+  const bases = [['calendar.base', resolved.base], ['calendar.eventsBase', resolved.eventsBase], ['calendar.bookBase', resolved.bookBase]];
+  for (const [label, base] of bases) {
+    if (typeof base !== 'string' || !/^\/[a-z0-9-]+(\/[a-z0-9-]+)*$/.test(base)) {
+      throw new Error(
+        `acms: ${label} must start with "/" and use lowercase letters, digits, and hyphens (no trailing slash) — got "${base}"`
+      );
+    }
+    if (RESERVED_BASES.has(base)) throw new Error(`acms: ${label} "${base}" collides with a built-in route — pick another path`);
+    if (enabled && contentBases.has(base)) {
+      throw new Error(`acms: ${label} "${base}" collides with ${contentBases.get(base)} — pick another path for one of them`);
+    }
+    if (enabled && locales.some((l) => `/${l}` === base)) {
+      throw new Error(`acms: ${label} "${base}" collides with the i18n locale prefix "${base}"`);
+    }
+  }
+  if (new Set(bases.map(([, b]) => b)).size !== bases.length) {
+    throw new Error('acms: calendar.base, calendar.eventsBase and calendar.bookBase must be different paths');
+  }
+  const fields = calendar.eventFields ?? [];
+  if (!Array.isArray(fields)) throw new Error('acms: calendar.eventFields must be an array of { key, label, type } objects');
+  const keys = new Set();
+  for (const [i, f] of fields.entries()) {
+    if (!f || typeof f !== 'object') throw new Error(`acms: calendar.eventFields[${i}] must be an object`);
+    const key = f.key;
+    if (typeof key !== 'string' || !/^[a-z][a-z0-9_]*$/.test(key)) {
+      throw new Error(`acms: calendar.eventFields[${i}].key must be lowercase letters, digits, and underscores, starting with a letter — got "${key}"`);
+    }
+    if (keys.has(key)) throw new Error(`acms: calendar.eventFields has two fields with the key "${key}"`);
+    keys.add(key);
+    const type = f.type ?? 'text';
+    if (!EVENT_FIELD_TYPES.includes(type)) {
+      throw new Error(`acms: calendar.eventFields "${key}" has type "${type}" — use one of ${EVENT_FIELD_TYPES.join(', ')}`);
+    }
+    const options = f.options ?? [];
+    if (!Array.isArray(options) || options.some((o) => typeof o !== 'string')) {
+      throw new Error(`acms: calendar.eventFields "${key}".options must be an array of strings`);
+    }
+    if (type === 'select' && options.length === 0) {
+      throw new Error(`acms: calendar.eventFields "${key}" is a select field — give it an options array`);
+    }
+    const label = f.label ?? key.charAt(0).toUpperCase() + key.slice(1).replace(/_/g, ' ');
+    if (typeof label !== 'string') throw new Error(`acms: calendar.eventFields "${key}".label must be a string`);
+    resolved.eventFields.push({ key, label, type, options });
+  }
+  if (resolved.eventFields.length > 30) throw new Error('acms: calendar.eventFields allows at most 30 fields');
+  return resolved;
+}
+
 const semverLt = (a, b) => {
   const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
   for (let i = 0; i < 3; i++) { if ((pa[i] ?? 0) < (pb[i] ?? 0)) return true; if ((pa[i] ?? 0) > (pb[i] ?? 0)) return false; }
@@ -236,11 +346,14 @@ const THEMES_ID = 'virtual:acms-user-themes';
 // they resolve against the consumer's src/ — the core's relative globs can't
 // see outside the package. Same folder contract as built-in themes.
 const USER_THEMES_CODE = `
+export const assets = import.meta.glob(['/src/themes/*/assets/**/*', '!**/.img-subir-originals/**'], { eager: true, query: '?url', import: 'default' });
+export const sectionTpls = import.meta.glob('/src/themes/*/sections/*.astro', { eager: true });
 export const jsons = import.meta.glob('/src/themes/*/theme.json', { eager: true, import: 'default' });
 export const csses = import.meta.glob('/src/themes/*/theme.css', { eager: true, query: '?raw', import: 'default' });
 export const homes = import.meta.glob('/src/themes/*/templates/home.astro', { eager: true });
 export const postTpls = import.meta.glob('/src/themes/*/templates/post-*.astro', { eager: true });
 export const pageTpls = import.meta.glob('/src/themes/*/templates/page-*.astro', { eager: true });
+export const eventTpls = import.meta.glob('/src/themes/*/templates/event.astro', { eager: true });
 `;
 
 function acmsVitePlugin(userConfig) {
@@ -284,6 +397,15 @@ function acmsVitePlugin(userConfig) {
  *   Public site search: the /search page, the /api/search JSON endpoint, 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]
+ *   Calendar module: the main calendar page at `base` (default '/calendar')
+ *   with subscribe feeds (`<base>.ics`, `<base>/<slug>.ics`), event pages at
+ *   `eventsBase` (default '/events'), a public JSON API under /api/calendar,
+ *   embeds, and the admin Calendar section. `eventFields` adds custom fields
+ *   to every event (edited in the event sidebar, exposed to templates and the
+ *   API). On by default — `calendar: false` removes all of it.
+ * @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.
  * @returns {import('astro').AstroIntegration}
  */
 export default function acms(options = {}) {
@@ -294,6 +416,11 @@ export default function acms(options = {}) {
   ]);
   const i18n = resolveI18n(options.i18n, contentBases);
   const search = resolveSearch(options.search);
+  const calendar = resolveCalendar(options.calendar, contentBases, i18n.locales);
+  const legal = { enabled: true, operatorName: '', contactEmail: '', updatedAt: '', ...(options.legal === false ? { enabled: false } : options.legal ?? {}) };
+  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 userConfig = {
     coreVersion: CORE_VERSION,
     brand: options.brand ?? {},
@@ -301,8 +428,14 @@ export default function acms(options = {}) {
     content,
     i18n,
     search,
+    calendar,
+    legal,
   };
-  const routes = [...ROUTES];
+  const routes = [...ROUTES,
+    ['/api/v1/content', 'api/v1/content/index.ts'],
+    ['/api/v1/content/[id]', 'api/v1/content/[id].ts'],
+  ];
+  if (legal.enabled) routes.push(['/privacy', 'legal/privacy.astro'], ['/terms', 'legal/terms.astro']);
   for (const c of Object.values(content.collections)) {
     routes.push([c.base, 'blog/index.astro'], [`${c.base}/[slug]`, 'blog/[slug].astro']);
   }
@@ -320,12 +453,59 @@ export default function acms(options = {}) {
       if (l !== i18n.defaultLocale) routes.push([`/${l}/search`, 'search.astro']);
     }
   }
+  if (calendar.enabled) {
+    routes.push(
+      [calendar.base, 'calendar/index.astro'],
+      [`${calendar.base}.ics`, 'calendar/feed.ics.ts'],
+      [`${calendar.base}/[slug].ics`, 'calendar/[slug].ics.ts'],
+      [`${calendar.eventsBase}/[slug]`, 'events/[slug].astro'],
+      [`${calendar.eventsBase}/[slug].ics`, 'events/[slug].ics.ts'],
+      ['/embed/calendar/[slug]', 'embed/calendar/[slug].astro'],
+      ['/api/v1/events', 'api/v1/events.ts'],
+      ['/api/v1/calendars', 'api/v1/calendars.ts'],
+      ['/api/calendar/events', 'api/calendar/events/index.ts'],
+      ['/api/calendar/calendars', 'api/calendar/calendars.ts'],
+      ['/admin/calendar', 'admin/calendar/index.ts'],
+      ['/admin/calendar/events', 'admin/calendar/events/index.astro'],
+      ['/admin/calendar/events/[id]', 'admin/calendar/events/[id].astro'],
+      ['/admin/calendar/calendars', 'admin/calendar/calendars.astro'],
+      ['/admin/calendar/integrations', 'admin/calendar/integrations.astro'],
+      ['/api/calendar/docs', 'api/calendar/docs.ts'],
+    );
+    if (calendar.bookings) {
+      routes.push(
+        [calendar.bookBase, 'book/index.astro'],
+        [`${calendar.bookBase}/manage/[token]`, 'book/manage/[token].astro'],
+        [`${calendar.bookBase}/[resource].ics`, 'book/[resource].ics.ts'],
+        [`${calendar.bookBase}/[resource]`, 'book/[resource]/index.astro'],
+        [`${calendar.bookBase}/[resource]/[link]`, 'book/[resource]/[link].astro'],
+        ['/embed/book/[resource]/[link]', 'embed/book/[resource]/[link].astro'],
+        ['/api/v1/resources', 'api/v1/resources.ts'],
+        ['/api/v1/availability', 'api/v1/availability.ts'],
+        ['/api/v1/bookings', 'api/v1/bookings.ts'],
+        ['/api/calendar/availability', 'api/calendar/availability.ts'],
+        ['/api/calendar/bookings', 'api/calendar/bookings/index.ts'],
+        ['/api/calendar/bookings/[id]', 'api/calendar/bookings/[id].ts'],
+        ['/api/calendar/resources', 'api/calendar/resources.ts'],
+        ['/admin/calendar/bookings', 'admin/calendar/bookings.astro'],
+        ['/admin/calendar/resources', 'admin/calendar/resources/index.astro'],
+        ['/admin/calendar/resources/[id]', 'admin/calendar/resources/[id].astro'],
+        ['/admin/calendar/resources/[id]/links/[link]', 'admin/calendar/resources/link.astro'],
+      );
+    }
+    routes.push(['/api/calendar/events/[id]', 'api/calendar/events/[id].ts']);
+  }
   let cacheDir = '';
   return {
     name: 'acms',
     hooks: {
       'astro:config:setup': ({ config, command, injectRoute, addMiddleware, updateConfig }) => {
         if (config.cacheDir) cacheDir = fileURLToPath(config.cacheDir);
+        if (config.root) {
+          const discoveryDir = fileURLToPath(new URL('.astro/', config.root));
+          mkdirSync(discoveryDir, {recursive:true});
+          writeFileSync(join(discoveryDir,'acms-project.json'), JSON.stringify({ themeApiVersion:1, collections:userConfig.content.collections, calendar:userConfig.calendar }));
+        }
         updateConfig({ vite: { plugins: [acmsVitePlugin(userConfig)] } });
 
         // "Project-local routes win" is enforced here: Astro registers
@@ -357,6 +537,17 @@ export default function acms(options = {}) {
             vite: { resolve: { alias: { 'react-dom/server': 'react-dom/server.edge' } } },
           });
         }
+        // The Docker runtime image installs only @libsql/client, so the
+        // standalone bundle must carry every other dependency. Left to its
+        // default, Vite externalizes package imports (react-dom, astro's
+        // runtime, zod, marked, …) and the server crashes on its first
+        // import in the container. @libsql/client stays external: it is
+        // dynamically imported and ships native bindings.
+        if (target === 'node' && command === 'build') {
+          updateConfig({
+            vite: { ssr: { noExternal: true, external: ['@libsql/client'] } },
+          });
+        }
       },
       // fires only for `astro dev` — builds and previews never phone anywhere
       'astro:server:start': ({ logger }) => {

package/ops-check.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Never accepts a credential in an argument or prints a response body.
+const base = process.env.ACMS_SITE_URL;
+const secret = process.env.EMAIL_RUNNER_SECRET;
+if (!base || !secret || secret.length < 32) {
+  console.error('Set ACMS_SITE_URL and EMAIL_RUNNER_SECRET in your environment. Optional: --storage-check'); process.exit(1);
+}
+const origin = new URL(base);
+if (origin.username || origin.password || (origin.protocol !== 'https:' && !(origin.protocol === 'http:' && ['localhost','127.0.0.1','[::1]'].includes(origin.hostname)))) {
+  console.error('Use HTTPS, or HTTP on localhost for local testing.'); process.exit(1);
+}
+let failed = false;
+async function check(label, path, options = {}, predicate = r => r.ok) {
+  try {
+    const response = await fetch(new URL(path, origin), { ...options, redirect: 'error', signal: AbortSignal.timeout(15000) });
+    const ok = await predicate(response);
+    await response.body?.cancel().catch(() => {});
+    console.log(`${ok ? 'PASS' : 'FAIL'} ${label}`); if (!ok) failed = true;
+  } catch { console.log(`FAIL ${label}`); failed = true; }
+}
+await check('public content API', '/api/v1/content?limit=1', {}, async r => r.ok && (await r.json()).version === 1);
+await check('privacy page', '/privacy');
+await check('terms page', '/terms');
+const headers = { authorization: `Bearer ${secret}`, 'Content-Type': 'application/json', Origin: origin.origin };
+await check('database, HTTPS settings, secrets and scheduler heartbeat', '/api/ops/status', { headers }, async r => r.ok && (await r.json()).ok === true);
+if (process.argv.includes('--storage-check')) await check('media write/read/delete probe', '/api/ops/status', { method: 'POST', headers }, async r => r.ok && (await r.json()).ok === true);
+process.exitCode = failed ? 1 : 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -22,7 +22,9 @@
     "workers"
   ],
   "bin": {
-    "acms": "./cli.mjs"
+    "acms": "cli.mjs",
+    "acms-email-runner": "email-runner.mjs",
+    "acms-check-deployment": "ops-check.mjs"
   },
   "exports": {
     ".": "./integration.mjs",
@@ -35,32 +37,50 @@
     "./components/*": "./src/components/*",
     "./layouts/*": "./src/layouts/*",
     "./styles/*": "./src/styles/*",
-    "./themes/*": "./src/themes/*"
+    "./themes/*": "./src/themes/*",
+    "./theme": "./src/theme-sdk/index.ts",
+    "./theme/schema": "./src/theme-sdk/contract.mjs",
+    "./theme/components/*": "./src/components/site/*"
   },
   "files": [
     "integration.mjs",
     "cli.mjs",
     "src",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "email-runner.mjs",
+    "deploy",
+    "ops-check.mjs",
+    "cli",
+    "docs"
   ],
   "dependencies": {
+    "@cloudflare/workers-types": "^5.20260927.1",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@libsql/client": "^0.15.0",
-    "@tiptap/extension-code-block-lowlight": "^3.29.2",
-    "@tiptap/extension-table": "^3.29.2",
-    "@tiptap/extensions": "^3.29.2",
-    "@tiptap/pm": "^3.29.2",
-    "@tiptap/react": "^3.29.2",
-    "@tiptap/starter-kit": "^3.29.2",
-    "@tiptap/suggestion": "^3.29.2",
+    "@tiptap/extension-code-block-lowlight": "^3.30.1",
+    "@tiptap/extension-highlight": "3.30.1",
+    "@tiptap/extension-table": "^3.30.1",
+    "@tiptap/extensions": "^3.30.1",
+    "@tiptap/pm": "^3.30.1",
+    "@tiptap/react": "^3.30.1",
+    "@tiptap/starter-kit": "^3.30.1",
+    "@tiptap/suggestion": "^3.30.1",
+    "franc-min": "^6.2.0",
     "hast-util-to-html": "^9.0.5",
     "lowlight": "^3.3.0",
+    "mammoth": "^1.12.3",
     "marked": "^15.0.0",
+    "pdfjs-dist": "^6.3.289",
     "prismjs": "^1.30.0",
+    "sanitize-html": "^2.17.7",
     "simple-icons": "^16.27.1",
-    "zod": "^3.24.0"
+    "turndown": "^7.2.4",
+    "zod": "^3.24.0",
+    "zod-to-json-schema": "^3.25.2",
+    "semver": "^7.7.2",
+    "tar": "^7.5.1"
   },
   "peerDependencies": {
     "@astrojs/cloudflare": "^12.6.13",
@@ -82,6 +102,9 @@
     "@types/prismjs": "^1.26.6",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
+    "@types/sanitize-html": "^2.16.1",
+    "@types/turndown": "^5.0.6",
+    "miniflare": "^5.20260801.0-alpha",
     "vitest": "^3.2.0"
   },
   "scripts": {