@acms-subir/core 0.2.0 → 0.3.1

package/deploy/compose.yml

@@ -0,0 +1,46 @@
+# Connect your existing proxy to this Compose network and route to site:4321.
+# Optional standalone TLS: docker compose -f compose.yml -f compose.https.yml up -d --build
+services:
+  site:
+    build: &site-build .
+    init: true
+    restart: unless-stopped
+    expose:
+      - "4321"
+    volumes:
+      - data:/app/data
+    environment:
+      - HOST=0.0.0.0
+      - PORT=4321
+      - ADMIN_PASSWORD=${ADMIN_PASSWORD:?set ADMIN_PASSWORD in .env}
+      - SESSION_SECRET=${SESSION_SECRET:?set SESSION_SECRET in .env}
+      - EMAIL_RUNNER_SECRET=${EMAIL_RUNNER_SECRET:?set EMAIL_RUNNER_SECRET in .env}
+      - EMAIL_ENCRYPTION_KEY=${EMAIL_ENCRYPTION_KEY:-}
+      - 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))"]
+      interval: 60s
+      timeout: 15s
+      start_period: 30s
+  scheduler:
+    build: *site-build
+    init: true
+    restart: unless-stopped
+    # Share only the app network namespace. No public port or database volume.
+    network_mode: service:site
+    depends_on:
+      site:
+        condition: service_healthy
+        restart: true
+    command: ["node", "/app/email-runner.mjs"]
+    environment:
+      - EMAIL_RUNNER_URL=http://127.0.0.1:4321
+      - EMAIL_RUNNER_SECRET=${EMAIL_RUNNER_SECRET:?set EMAIL_RUNNER_SECRET in .env}
+      - SCHEDULER_HEARTBEAT_FILE=/tmp/acms-scheduler-heartbeat
+    healthcheck:
+      test: ["CMD", "node", "-e", "const fs=require('fs');try{process.exit(Date.now()-Number(fs.readFileSync('/tmp/acms-scheduler-heartbeat','utf8'))<180000?0:1)}catch{process.exit(1)}"]
+      interval: 60s
+      timeout: 5s
+      start_period: 120s
+volumes:
+  data:

package/docs/live-video.md

@@ -0,0 +1,91 @@
+# Live video connections
+
+ACMS can discover a site's current YouTube or Twitch broadcast and display it on its homepage and links page. Each site owner registers their own developer application and supplies its credentials. ACMS makes API requests from the deployed site's server; there is no shared ACMS developer app, hosted proxy or shared quota. The streaming platform continues to broadcast and host the video.
+
+Open **Integrations → Live video** (`/admin/live`) as an owner. Connect a provider, run a successful test, turn the connection on, and save the display mode as **Automatic**. A healthy connection can be offline: starting a broadcast happens on the streaming platform, not in ACMS.
+
+## Before connecting
+
+- Set the site's canonical URL in Settings. Use that exact origin to sign in and authorize YouTube, including whether it uses `www`. Production callbacks require HTTPS; localhost HTTP is allowed for development.
+- Supply a strong `SESSION_SECRET` (at least 32 random characters), or a separate `LIVE_ENCRYPTION_KEY` of that length, using the host's secret configuration. Live credentials use AES-256-GCM and a separate encryption context. An explicit live key takes precedence. Losing/changing the effective encryption key requires re-entering credentials and reauthorizing.
+- Ensure the independent scheduler runs every minute. Workers deployments use the existing scheduled handler/cron trigger; self-hosted Docker uses the existing supervised scheduler. Custom Node deployments must invoke the existing authenticated `/api/email/run` runner, which now also runs live checks. It is a shared operational runner despite its historical name. See [production deployment](../../../docs/production-deployment.md). Visitor traffic does not drive live-provider polling.
+- The UI reports the live scheduler heartbeat, each connection's last successful check, next due check and any provider error. Public visitors only receive a sanitized snapshot.
+
+## Twitch
+
+1. Open the [Twitch application console](https://dev.twitch.tv/console/apps) and register a **Confidential** application. Follow Twitch's account/2FA requirements.
+2. If registration requests an OAuth redirect URI, use the copyable address shown by ACMS (`https://your-site.example/admin/live`). This app-only lookup does not use a Twitch OAuth callback or broadcaster sign-in.
+3. Copy the Client ID and generate/copy the Client Secret. Enter them with the channel username or HTTPS channel URL in ACMS.
+4. Save, test, and turn the connection on. The test resolves the channel's stable ID.
+
+ACMS obtains an app token with the client-credentials flow and checks Get Streams for that broadcaster. App tokens are [validated](https://dev.twitch.tv/docs/authentication/validate-tokens/) when acquired and hourly during use. Expired or revoked app tokens are reacquired; these tokens do not use refresh tokens. ACMS requests no stream key or broadcast-management permissions. See [app registration](https://dev.twitch.tv/docs/authentication/register-app/), [token flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#client-credentials-grant-flow), and [Get Streams](https://dev.twitch.tv/docs/api/reference/#get-streams).
+
+## YouTube
+
+1. Create/select a Google Cloud project and enable **YouTube Data API v3**.
+2. Configure OAuth consent for the appropriate audience. During external-app testing, add the Google account that owns the intended channel as a test user.
+3. Create an OAuth **Web application** client. Copy the exact callback shown in ACMS into Google's authorized redirect URIs: `https://your-site.example/api/live/oauth/youtube/callback`.
+4. Save the Client ID and Client Secret in ACMS, then choose **Authorize YouTube**. Approve YouTube read-only access using the correct Google/Brand channel identity.
+5. Confirm the available channel, test, and turn the connection on. Selecting another channel requires a new test. A typed channel ID cannot override the authorized identity.
+
+The authorization-code flow uses session-bound, one-use state and PKCE. Access/refresh tokens stay encrypted on the server. ACMS lists active broadcasts, filters to the selected channel and public `live` broadcasts, and checks public video visibility/embedding permission. Private, unlisted and test broadcasts are excluded. Multiple current broadcasts use the latest actual start time with a stable ID tie-break. See [liveBroadcasts.list](https://developers.google.com/youtube/v3/live/docs/liveBroadcasts/list) and [server OAuth](https://developers.google.com/identity/protocols/oauth2/web-server).
+
+External OAuth apps left in **Testing** receive refresh tokens for YouTube scopes that expire after seven days. The UI's Testing/Production choice is owner-reported; ACMS cannot verify the app's publishing status. Follow Google's applicable publishing and verification requirements before relying on a long-running connection. A revoked or expired grant requires reauthorization. See [Google token expiration](https://developers.google.com/identity/protocols/oauth2#expiration).
+
+### Quota and timing
+
+The normal target is a check each minute and visible changes within roughly one to two minutes, subject to provider latency, scheduler operation and quota. One single-page active-broadcast list per minute is about 1,440 units/day before extra calls. Live-video visibility checks, connection tests, pagination and optional upcoming lookups add usage. Check the owner's actual project limits and other apps sharing that project.
+
+Current Google documentation assigns `liveBroadcasts.list` a cost of one unit, with a default shared 10,000-unit daily allocation for non-search/non-upload endpoints. Public `search.list` has a separate default 100-call daily allowance. ACMS therefore implements owner-authorized OAuth, not minute-by-minute public search. API-key-only discovery is not included in this release. See [Google's current quota table](https://developers.google.com/youtube/v3/determine_quota_cost).
+
+Rate-limit/quota errors back off. The UI reports estimated workload and provider errors, not an invented remaining quota. Optional YouTube upcoming lookup is cached for up to 15 minutes while active detection continues normally. A scheduled start time never becomes a live badge on its own.
+
+## Place the live card
+
+- **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.
+
+### How it looks
+
+**What your site shows → How it looks** (shown unless live video is Off) controls presentation:
+
+- **Card style** for sections set to `card`: **Poster** (thumbnail with a live tag, title below; default), **Split** (thumbnail beside the title; stacks in columns narrower than 700px) or **Compact row**. Sections set to `player` always use the split layout, with the poster as the play button. The Links block is its own compact layout and moves to the top of the Links page while you're live.
+- **Thumbnail** (on by default): served from `/api/live/thumb`, which fetches the current broadcast's still from YouTube (`i.ytimg.com`) or Twitch (`static-cdn.jtvnw.net`) on the server and caches it for a minute. Visitors never contact the platform until they press play. The upstream URL is derived only from the current snapshot's validated id; the query string is a cache version.
+- **Viewer count** (off by default): Twitch reports it in the existing streams call; YouTube adds `liveStreamingDetails` to the existing `videos.list` check at the same one-unit cost. It is only sent to visitors when this is on.
+- **Site-wide signals** (all off by default), shown on every page only while a broadcast is live: a **live bar** that temporarily replaces the announcement bar, a **"Live" marker** in the header, and a **floating card** in the corner (hidden on pages that already show a live card). The bar and card can be dismissed for the rest of that broadcast in the visitor's session. They are filled in by the browser from `/api/live/status`, so pages keep their normal caching.
+
+Offline, a card shows a single "Not live right now · Watch our channel" row when an offline link is set, and hides otherwise. Upcoming broadcasts show their start time on the poster ("Sat 7:00 PM · in 2 h").
+
+### Theming
+
+The markup is a stable class API: `.pc-live` with `data-layout` (`poster`, `split`, `row`, `links`) and `data-status` (`live`, `upcoming`, `offline`); parts `.pc-live-poster`, `.pc-live-tag`, `.pc-live-viewers`, `.pc-live-kicker`, `.pc-live-title-text`, `.pc-live-meta`, `.pc-live-btn`, `.pc-live-off`; site-wide `.pc-live-bar`, `.site-live`, `.pc-live-dock`. While a broadcast is live or upcoming, `<html data-live="live|upcoming">` is set, so a theme can style anything (for example `html[data-live='live'] .brand`).
+
+Override these on `:root` in `theme.css`: `--live-color` (defaults to the theme token `live`, a tuned red), `--live-ink`, `--live-radius`, `--live-tag-radius` (keep it a rectangle), `--live-poster-ratio` and `--live-pulse`. The marker blink is disabled under `prefers-reduced-motion`.
+
+All placements share the same status. Changing credentials or live mode takes effect independently of staged layout changes. Adding/reordering a placement still follows its existing save/publish workflow. Existing sites start with live display off.
+
+Player mode loads the official platform iframe only after a visitor clicks. Autoplay is off. The external watch link stays available when playback is blocked. Twitch requires HTTPS, the embedding hostname in `parent`, and at least 400×300 pixels; narrow slots use a watch link. YouTube embeds preserve an origin referrer. The compact links card never embeds a player. Cross-domain embedding of an entire ACMS site may require additional Twitch parent domains and is not configured automatically. See [Twitch embeds](https://dev.twitch.tv/docs/embed/video-and-clips/) and [YouTube players](https://developers.google.com/youtube/iframe_api_reference).
+
+## Manual, off, fallback and outages
+
+**Manual** accepts an HTTPS watch URL and a bounded expiry of up to 12 hours (UI default: four hours). It overrides automatic detection until it expires; automatic detection then resumes. **End manual link now** resumes automatic immediately. **Off** hides every placement; turn off individual provider connections too if you want to stop their background checks.
+
+An optional neutral “Watch our channel” URL appears when no fresh live/upcoming broadcast is available. Provider priority chooses the first currently live enabled source; a live source always takes precedence over an upcoming one. No replay is automatically labelled live, and replay libraries are not part of this release.
+
+A successful live observation expires after two minutes. Failures never extend that expiry. A confirmed offline result clears the badge, revoked access clears live state and disables that connection, and expired state hides the badge. Visible browser tabs refresh the sanitized status every 30 seconds and on focus; an expiry timer removes stale badges even if requests fail. Without JavaScript, status refreshes on the next page load. Pages containing live cards and the public status endpoint are not cached.
+
+## Storage, permissions and recovery
+
+Migration 34 adds a `settings.live` display configuration, a separate `live_connections` vault, one-use `live_oauth_states`, and a live scheduler heartbeat. Credentials never enter generic Settings, theme props, public API responses, React hydration or ordinary content exports. Owner-only APIs use existing authenticated sessions plus same-origin writes. Public `/api/live/status` only returns the selected public snapshot and server time.
+
+Each background check claims a durable lease. Settings revisions and lease tokens prevent a delayed check from overwriting a newer edit/disconnection; concurrent runners cannot refresh the same connection simultaneously. Requests have timeouts, response-size limits and redacted errors. Provider requests use fixed official endpoints; pasted URLs are never fetched by the server.
+
+Saving a connection disables it until tested again. Blank secrets preserve the saved secret only for the same client ID; changing the client ID or supplying a new secret clears incompatible authorization. Disconnect removes local credentials and state immediately and attempts provider revocation. Other applications using the same owner developer project may share quota or authorization consequences.
+
+Content backups include inert display preferences but no connection secrets or tokens. Restore forces live mode off and disables any destination connections until retested; it neither imports credentials nor resumes a copied live badge. On a new host, enter app credentials, update Google's callback, authorize and test again.
+
+Facebook HTTPS watch links work in manual mode. A Facebook automatic Page connector, Twitch EventSub and the slower YouTube API-key mode remain separate follow-up releases. They are not represented as working connectors in the UI.
+
+Validation uses simulated provider HTTP responses for token renewal, filtering, expiry, quotas and OAuth attacks, plus SQLite/D1 concurrency and real local HTTP rendering tests. A real owner-owned Twitch/Google app is still needed to validate its external consent and account permissions end to end.

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,36 @@ const ROUTES = [
   ['/admin/posts', 'admin/posts/index.astro'],
   ['/admin/posts/[id]', 'admin/posts/[id].astro'],
   ['/admin/settings', 'admin/settings.astro'],
+  ['/admin/integrations', 'admin/integrations.astro'],
+  ['/admin/live', 'admin/live.astro'],
+  ['/api/live/settings', 'api/live/settings.ts'],
+  ['/api/live/status', 'api/live/status.ts'],
+  ['/api/live/thumb', 'api/live/thumb.ts'],
+  ['/api/live/oauth/youtube/callback', 'api/live/oauth/youtube/callback.ts'],
+  ['/api/webhooks/docs', 'api/webhooks/docs.ts'],
+  ['/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 +91,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 +225,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 +353,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 +404,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 +423,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 +435,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 +460,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

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;