@glw907/cairn-cms 0.41.0 → 0.50.0

package/src/lib/delivery/sitemap.ts

@@ -1,5 +1,6 @@
 // cairn-cms: sitemap builder (public-delivery design). Pure over a URL list; the caller
 // derives the list from the content index and the routable concepts.
+import { escapeXml } from './xml.js';
 
 /** One sitemap URL. `lastmod` is a YYYY-MM-DD date. */
 export interface SitemapUrl {
@@ -7,10 +8,6 @@ export interface SitemapUrl {
   lastmod?: string;
 }
 
-function escapeXml(value: string): string {
-  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-
 /** Build a sitemap XML document from a list of URLs. */
 export function buildSitemap(urls: SitemapUrl[]): string {
   const entries = urls

package/src/lib/delivery/xml.ts

@@ -0,0 +1,12 @@
+// cairn-cms: the one XML text escape the feed and sitemap builders share. The strongest of the
+// two copies it replaced (the old sitemap copy skipped quotes), so both documents stay safe in
+// element text and double-quoted attributes.
+
+/** Escape the XML-significant characters for element text and double-quoted attribute values. */
+export function escapeXml(value: string): string {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}

package/src/lib/email.ts

@@ -3,6 +3,7 @@
 // (Cloudflare Email Sending, arbitrary recipients).
 import type { AuthEnv } from './auth/types.js';
 import { CairnError } from './diagnostics/index.js';
+import { escapeHtml } from './escape.js';
 
 export type { AuthEnv };
 
@@ -27,16 +28,6 @@ export interface AuthBranding {
  *  the message body or the magic link in what it throws. */
 export type SendMagicLink = (env: AuthEnv, message: MagicLinkMessage) => Promise<void>;
 
-/** Escape the five HTML-significant characters. */
-function escapeHtml(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#39;');
-}
-
 /** Build the confirmation email. The link is the only action; the copy stays plain. */
 export function buildMagicLinkMessage(input: {
   to: string;
@@ -54,7 +45,9 @@ export function buildMagicLinkMessage(input: {
 
 /** The production send: Cloudflare Email Sending through the EMAIL binding. */
 export const cloudflareSend: SendMagicLink = async (env, message) => {
-  if (!env.EMAIL) throw new Error('EMAIL binding is not configured');
+  if (!env.EMAIL) {
+    throw new CairnError('config.bindings-missing', { message: 'EMAIL binding is not configured' });
+  }
   await env.EMAIL.send(message);
 };
 

package/src/lib/env.ts

@@ -1,4 +1,5 @@
 import type { D1Database } from '@cloudflare/workers-types';
+import { CairnError } from './diagnostics/index.js';
 
 /**
  * Returns the site's public origin from configuration.
@@ -35,11 +36,11 @@ export function requireOrigin(env: { PUBLIC_ORIGIN?: string }): string {
  * The handlers read D1 off `event.platform.env`; without this a misconfigured binding
  * surfaces as a raw `TypeError` deep in a store call. This gives the failure a name.
  *
- * @throws Error when `AUTH_DB` is missing.
+ * @throws CairnError (`config.bindings-missing`) when `AUTH_DB` is missing.
  */
 export function requireDb(env: { AUTH_DB?: D1Database }): D1Database {
   if (!env.AUTH_DB) {
-    throw new Error('AUTH_DB binding is not configured');
+    throw new CairnError('config.bindings-missing', { message: 'AUTH_DB binding is not configured' });
   }
   return env.AUTH_DB;
 }

package/src/lib/escape.ts

@@ -0,0 +1,12 @@
+// cairn-cms: the one HTML text escape. A leaf module with no imports, so the email builder and
+// the edge-served admin pages share it without either arm reaching into the other.
+
+/** Escape the five HTML-significant characters for text and quoted attribute values. */
+export function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}

package/src/lib/github/credentials.ts

@@ -2,6 +2,7 @@
 // App signer's input. One tested place owns the join and the missing-secret failure, so the
 // save action (Plan 05) stays thin and a misconfigured Worker fails by name, not with a deep
 // TypeError. Mirrors requireDb/requireOrigin in env.ts.
+import { CairnError } from '../diagnostics/index.js';
 import type { BackendConfig } from '../content/types.js';
 import type { AppCredentials } from './types.js';
 
@@ -12,7 +13,8 @@ export interface GithubKeyEnv {
 
 /**
  * Assemble the `AppCredentials` the signer needs from the adapter's `backend` (app id,
- * installation) and the Worker's private-key secret. Throws when the secret is unset.
+ * installation) and the Worker's private-key secret. Throws a CairnError naming
+ * `github.app-unreachable` when the secret is unset, since the App cannot authenticate without it.
  */
 export function appCredentials(
   backend: Pick<BackendConfig, 'appId' | 'installationId'>,
@@ -20,7 +22,9 @@ export function appCredentials(
 ): AppCredentials {
   const privateKeyB64 = env.GITHUB_APP_PRIVATE_KEY_B64;
   if (!privateKeyB64) {
-    throw new Error('GITHUB_APP_PRIVATE_KEY_B64 is not configured');
+    throw new CairnError('github.app-unreachable', {
+      message: 'GITHUB_APP_PRIVATE_KEY_B64 is not configured',
+    });
   }
   return { appId: backend.appId, installationId: backend.installationId, privateKeyB64 };
 }

package/src/lib/github/types.ts

@@ -43,3 +43,8 @@ export class CommitConflictError extends Error {
     this.name = 'CommitConflictError';
   }
 }
+
+/** Match a commit conflict by class and by name (bundling can alias the class identity). */
+export function isConflict(err: unknown): boolean {
+  return err instanceof CommitConflictError || (err as { name?: string } | null)?.name === 'CommitConflictError';
+}

package/src/lib/log/events.ts

@@ -10,6 +10,7 @@ export type CairnLogEvent =
   | 'auth.session.destroyed'
   | 'commit.succeeded'
   | 'commit.failed'
+  | 'config.invalid'
   | 'entry.published'
   | 'entry.discarded'
   | 'publish.failed'

package/src/lib/nav/site-config.ts

@@ -85,6 +85,9 @@ export interface SiteConfig {
 }
 
 export class SiteConfigError extends Error {
+  /** The registered diagnostic condition a malformed site config maps to (mirrors CairnError). */
+  readonly conditionId = 'config.site-config-invalid';
+
   constructor(message: string) {
     super(message);
     this.name = 'SiteConfigError';

package/src/lib/sveltekit/admin-dispatch.ts

@@ -0,0 +1,75 @@
+// cairn-cms: the single path authority for the single-mount admin dispatcher. The dispatcher
+// mounts one catch-all route under /admin and asks this parser which view a raw pathname
+// names; every admin URL shape is decided here and nowhere else. The parser is pure: it
+// returns a discriminated AdminView, or null for any shape it does not recognize, and the
+// caller maps null to a 404.
+import type { ConceptDescriptor } from '../content/types.js';
+import { findConcept } from '../content/concepts.js';
+import { isValidId } from '../content/ids.js';
+
+/** The views the single-mount admin can render, discriminated for the dispatcher's switch. */
+export type AdminView =
+  | { view: 'index' }
+  | { view: 'login' }
+  | { view: 'confirm' }
+  | { view: 'list'; concept: ConceptDescriptor }
+  | { view: 'edit'; concept: ConceptDescriptor; id: string }
+  | { view: 'editors' }
+  | { view: 'nav' };
+
+/**
+ * Fixed first segments that never resolve as concepts. The engine only allows posts and pages
+ * today, so no collision is possible, but the parser does not depend on that: a reserved
+ * segment wins before concept lookup. `settings` has no view yet; AdminLayout already links
+ * the sidebar to /admin/settings, so the URL is spoken for.
+ */
+const RESERVED_SEGMENTS = new Set(['login', 'auth', 'editors', 'nav', 'settings']);
+
+/**
+ * Parse a raw `URL.pathname` (the caller passes `event.url.pathname`, never a SvelteKit rest
+ * param) into the admin view it names. A single trailing slash is tolerated everywhere; empty
+ * internal segments are not. Each segment is percent-decoded individually, so an encoded slash
+ * stays inside its segment, where it can never match a concept id or pass `isValidId` and so
+ * falls through to null.
+ */
+export function parseAdminPath(
+  pathname: string,
+  concepts: ConceptDescriptor[],
+): AdminView | null {
+  if (pathname !== '/admin' && !pathname.startsWith('/admin/')) return null;
+  let rest = pathname.slice('/admin'.length);
+  // Tolerate exactly one trailing slash; a doubled one leaves an empty segment behind.
+  if (rest.endsWith('/')) rest = rest.slice(0, -1);
+  if (rest === '') return { view: 'index' };
+
+  const rawSegments = rest.slice(1).split('/');
+  if (rawSegments.includes('')) return null;
+  let segments: string[];
+  try {
+    segments = rawSegments.map((segment) => decodeURIComponent(segment));
+  } catch {
+    // Malformed percent encoding is an unrecognized shape, not a server error.
+    return null;
+  }
+
+  if (segments.length === 1) {
+    const [head] = segments;
+    if (head === 'login') return { view: 'login' };
+    if (head === 'editors') return { view: 'editors' };
+    if (head === 'nav') return { view: 'nav' };
+    if (RESERVED_SEGMENTS.has(head)) return null;
+    const concept = findConcept(concepts, head);
+    return concept ? { view: 'list', concept } : null;
+  }
+
+  if (segments.length === 2) {
+    const [head, tail] = segments;
+    if (head === 'auth') return tail === 'confirm' ? { view: 'confirm' } : null;
+    if (RESERVED_SEGMENTS.has(head)) return null;
+    const concept = findConcept(concepts, head);
+    if (!concept || !isValidId(tail)) return null;
+    return { view: 'edit', concept, id: tail };
+  }
+
+  return null;
+}

package/src/lib/sveltekit/cairn-admin.ts

@@ -0,0 +1,177 @@
+// The single-mount admin facade. One factory closes over the composed runtime, instantiates
+// the existing per-surface route factories (auth, content, editors, nav), and serves every
+// admin view through the one load and one actions record a site's catch-all /admin/[...path]
+// route exports. The path authority is admin-dispatch's parseAdminPath; this module only maps
+// each view to the wrapped load it delegates to, and each named action validates that the
+// parsed view supports it before delegating to the same wrapped factories.
+import { error } from '@sveltejs/kit';
+import { parseAdminPath, type AdminView } from './admin-dispatch.js';
+import { createAuthRoutes } from './auth-routes.js';
+import {
+  createContentRoutes,
+  type ContentEvent,
+  type ContentRoutesDeps,
+  type LayoutData,
+  type ListData,
+  type EditData,
+} from './content-routes.js';
+import { createEditorRoutes } from './editors-routes.js';
+import { createNavRoutes, type NavLoadData } from './nav-routes.js';
+import type { AuthBranding, SendMagicLink } from '../email.js';
+import type { AuthEnv, Editor } from '../auth/types.js';
+import type { GithubKeyEnv } from '../github/credentials.js';
+import type { CairnRuntime } from '../content/types.js';
+import type { CookieJar, EventBase } from './types.js';
+
+/**
+ * The structural event the single-mount load reads: the union of what the wrapped loads need
+ * (ContentEvent minus params, which the dispatcher synthesizes, plus RequestContext's cookies
+ * and setHeaders). A real SvelteKit RequestEvent satisfies it.
+ */
+export interface AdminEvent extends EventBase<GithubKeyEnv & AuthEnv> {
+  cookies: CookieJar;
+  setHeaders(headers: Record<string, string>): void;
+}
+
+/** Injectable dependencies. Branding defaults from the runtime's siteName and sender, so a
+ *  site overrides it only to change the magic-link email identity; `send` and `mintToken`
+ *  are the same seams the underlying factories take. */
+export interface CairnAdminDeps {
+  branding?: AuthBranding;
+  send?: SendMagicLink;
+  mintToken?: ContentRoutesDeps['mintToken'];
+}
+
+/**
+ * One admin view's data, discriminated for the admin page component's switch. The public
+ * views (login, confirm) carry no layout; every authed view pairs the shared layout with its
+ * page data, the same shapes the per-surface loads have always returned.
+ */
+export type AdminData =
+  | { view: 'login'; page: { siteName: string; error: string | null; csrf: string } }
+  | { view: 'confirm'; page: { token: string; siteName: string; error: string | null; csrf: string } }
+  | { view: 'list'; layout: LayoutData; page: ListData }
+  | { view: 'edit'; layout: LayoutData; page: EditData }
+  | { view: 'editors'; layout: LayoutData; page: { editors: Editor[]; self: string } }
+  | { view: 'nav'; layout: LayoutData; page: NavLoadData };
+
+export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {}) {
+  // The runtime already composes the site name and the sender identity, so the magic-link
+  // branding needs no second copy of either unless a site overrides it.
+  const branding: AuthBranding = deps.branding ?? {
+    siteName: runtime.siteName,
+    from: runtime.sender.from,
+    replyTo: runtime.sender.replyTo,
+  };
+  const auth = createAuthRoutes({ branding, send: deps.send });
+  const content = createContentRoutes(runtime, { mintToken: deps.mintToken });
+  const editors = createEditorRoutes();
+  // The nav surface exists only when the site configures a menu; without one its view is a 404.
+  const nav = runtime.navMenu ? createNavRoutes(runtime, { mintToken: deps.mintToken }) : null;
+
+  /** Build the event a wrapped content load reads. The catch-all route carries only a rest
+   *  param, so `concept` and `id` are synthesized from the parsed view. The override names
+   *  each field explicitly rather than spreading: a real RequestEvent's fields can sit behind
+   *  getters a bare spread copies poorly, and the structural ContentEvent contract needs only
+   *  these. */
+  function contentEvent(event: AdminEvent, params: Record<string, string>): ContentEvent {
+    return {
+      url: event.url,
+      params,
+      request: event.request,
+      locals: event.locals,
+      platform: event.platform,
+      cookies: event.cookies,
+    };
+  }
+
+  /** Serve the admin view the pathname names, or a 404 for any shape the parser refuses.
+   *  The authed views run the layout load and the view load concurrently; both mint a GitHub
+   *  token, and the installation-token cache coalesces the mints into one signing. */
+  async function load(event: AdminEvent): Promise<AdminData> {
+    const view = parseAdminPath(event.url.pathname, runtime.concepts);
+    if (!view) throw error(404, 'Not found');
+    switch (view.view) {
+      case 'index':
+        return content.indexRedirect();
+      case 'login':
+        return { view: 'login', page: auth.loginLoad(event) };
+      case 'confirm':
+        return { view: 'confirm', page: auth.confirmLoad(event) };
+      case 'list': {
+        const delegated = contentEvent(event, { concept: view.concept.id });
+        const [layout, page] = await Promise.all([content.layoutLoad(delegated), content.listLoad(delegated)]);
+        return { view: 'list', layout, page };
+      }
+      case 'edit': {
+        const delegated = contentEvent(event, { concept: view.concept.id, id: view.id });
+        const [layout, page] = await Promise.all([content.layoutLoad(delegated), content.editLoad(delegated)]);
+        return { view: 'edit', layout, page };
+      }
+      case 'editors': {
+        // editorsLoad gates itself with requireOwner, so the dispatcher adds no second gate.
+        const [layout, page] = await Promise.all([
+          content.layoutLoad(contentEvent(event, {})),
+          editors.editorsLoad(event),
+        ]);
+        return { view: 'editors', layout, page };
+      }
+      case 'nav': {
+        if (!nav) throw error(404, 'Not found');
+        const delegated = contentEvent(event, {});
+        const [layout, page] = await Promise.all([content.layoutLoad(delegated), nav.navLoad(delegated)]);
+        return { view: 'nav', layout, page };
+      }
+    }
+  }
+
+  /** Wrap a delegate in the parse-and-check every action shares: parse the pathname exactly
+   *  as load does, 404 on a null parse or a view outside the allowed set, then hand the
+   *  narrowed view to the delegate. */
+  function viewAction<V extends AdminView['view'], R>(
+    allowed: readonly V[],
+    delegate: (event: AdminEvent, view: Extract<AdminView, { view: V }>) => Promise<R>,
+  ): (event: AdminEvent) => Promise<R> {
+    return async (event) => {
+      const view = parseAdminPath(event.url.pathname, runtime.concepts);
+      if (!view || !(allowed as readonly string[]).includes(view.view)) throw error(404, 'Not found');
+      // The includes check above proves the membership the cast asserts.
+      return delegate(event, view as Extract<AdminView, { view: V }>);
+    };
+  }
+
+  // The topbar posts publishAll from every authed admin page; login and confirm may not.
+  const authedViews = ['list', 'edit', 'editors', 'nav'] as const;
+  // An editor signs out from wherever they are, so logout accepts any parsed view.
+  const anyView = ['index', 'login', 'confirm', 'list', 'edit', 'editors', 'nav'] as const;
+
+  /** The full admin action vocabulary, one named async function per action, so a site's
+   *  catch-all route exports `admin.actions` directly. Each wrapper stays thin: parse,
+   *  validate the view, synthesize the params the wrapped action reads, delegate. The
+   *  editor actions gate themselves with requireOwner, so no second gate is added here. */
+  const actions = {
+    request: viewAction(['login'], (event) => auth.requestAction(event)),
+    confirm: viewAction(['confirm'], (event) => auth.confirmAction(event)),
+    logout: viewAction(anyView, (event) => auth.logoutAction(event)),
+    create: viewAction(['list'], (event, view) => content.createAction(contentEvent(event, { concept: view.concept.id }))),
+    save: viewAction(['edit', 'nav'], (event, view) => {
+      if (view.view === 'edit') return content.saveAction(contentEvent(event, { concept: view.concept.id, id: view.id }));
+      if (!nav) throw error(404, 'Not found');
+      return nav.navSave(contentEvent(event, {}));
+    }),
+    publish: viewAction(['edit'], (event, view) => content.publishAction(contentEvent(event, { concept: view.concept.id, id: view.id }))),
+    discard: viewAction(['edit'], (event, view) => content.discardAction(contentEvent(event, { concept: view.concept.id, id: view.id }))),
+    rename: viewAction(['edit'], (event, view) => content.renameAction(contentEvent(event, { concept: view.concept.id, id: view.id }))),
+    delete: viewAction(['edit', 'list'], (event, view) =>
+      view.view === 'edit'
+        ? content.deleteAction(contentEvent(event, { concept: view.concept.id, id: view.id }))
+        : content.listDeleteAction(contentEvent(event, { concept: view.concept.id })),
+    ),
+    publishAll: viewAction(authedViews, (event) => content.publishAllAction(contentEvent(event, {}))),
+    addEditor: viewAction(['editors'], (event) => editors.addEditorAction(event)),
+    removeEditor: viewAction(['editors'], (event) => editors.removeEditorAction(event)),
+    setRole: viewAction(['editors'], (event) => editors.setRoleAction(event)),
+  };
+
+  return { load, actions };
+}

package/src/lib/sveltekit/condition-response.ts

@@ -4,15 +4,38 @@
 import { brandedAdminPage } from './admin-response.js';
 import { httpsRequiredPage } from './https-required-page.js';
 import { csrfRequiredPage } from './csrf-required-page.js';
-import { condition } from '../diagnostics/index.js';
+import { escapeHtml } from '../escape.js';
+import { renderStaticAdminPage } from './static-admin-page.js';
+import { condition, type CairnCondition } from '../diagnostics/index.js';
 
 /** The guard.rejected reasons, each mapped to its registered condition id. */
 export const REASON_CONDITION = {
   https: 'edge.https-not-forced',
   csrf: 'auth.csrf-token-invalid',
   origin: 'auth.csrf-origin-mismatch',
+  bindings: 'config.bindings-missing',
 } as const;
 
+/**
+ * A branded page for an operator fault, built straight from the registered condition's fields so
+ * the served copy, the doctor's report, and the readiness checklist say the same thing.
+ */
+function conditionFaultPage(cond: CairnCondition): string {
+  const inner = `
+  <span class="eyebrow">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
+    Site setup required
+  </span>
+  <h1>${escapeHtml(cond.title)}</h1>
+  <p>${escapeHtml(cond.why)}</p>
+
+  <div class="fix">
+    <h2>If you run this site</h2>
+    <p>${escapeHtml(cond.remediation)}</p>
+  </div>`;
+  return renderStaticAdminPage({ title: `${cond.title} · Cairn`, innerHtml: inner });
+}
+
 export type GuardReason = keyof typeof REASON_CONDITION;
 
 /** Render the Response the guard serves for a rejection, by its condition id. */
@@ -32,6 +55,9 @@ export function renderConditionResponse(id: string, ctx: { url?: URL } = {}): Re
         status: 403,
         headers: { 'Content-Type': 'text/plain; charset=utf-8' },
       });
+    case REASON_CONDITION.bindings:
+      // An operator fault, not a request fault: the Worker deployed without its bindings.
+      return brandedAdminPage(500, conditionFaultPage(condition(id)));
     default:
       throw new Error(`no runtime renderer for condition: ${id}`);
   }