@glw907/cairn-cms 0.50.0 → 0.52.0

package/src/lib/env.ts

@@ -7,25 +7,30 @@ import { CairnError } from './diagnostics/index.js';
  * The origin is always config-derived, never read from a request header, so a
  * forged Host header cannot redirect a magic link (spec 7.1, risk H3).
  *
- * @throws Error when `PUBLIC_ORIGIN` is unset or empty.
+ * @throws CairnError (`config.public-origin-invalid`) when `PUBLIC_ORIGIN` is unset or
+ * empty, fails to parse as a URL, or uses http on a non-local host.
  */
 export function requireOrigin(env: { PUBLIC_ORIGIN?: string }): string {
   const origin = env.PUBLIC_ORIGIN;
   if (!origin) {
-    throw new Error('PUBLIC_ORIGIN is not configured');
+    throw new CairnError('config.public-origin-invalid', { message: 'PUBLIC_ORIGIN is not configured' });
   }
   let hostname: string;
   try {
     hostname = new URL(origin).hostname;
   } catch {
-    throw new Error(`PUBLIC_ORIGIN is not a valid URL, got ${origin}`);
+    throw new CairnError('config.public-origin-invalid', {
+      message: `PUBLIC_ORIGIN is not a valid URL, got ${origin}`,
+    });
   }
   // The magic-link origin must be https in production so the link and the __Host- cookie are
   // origin-bound. http is allowed only for local dev on localhost or 127.0.0.1, matched exactly so
   // a lookalike host like localhost.example.com cannot skip the https requirement.
   const isLocal = hostname === 'localhost' || hostname === '127.0.0.1';
   if (!origin.startsWith('https://') && !isLocal) {
-    throw new Error(`PUBLIC_ORIGIN must be https in production, got ${origin}`);
+    throw new CairnError('config.public-origin-invalid', {
+      message: `PUBLIC_ORIGIN must be https in production, got ${origin}`,
+    });
   }
   return origin;
 }

package/src/lib/index.ts

@@ -20,6 +20,8 @@ export type {
   BackendConfig,
   SenderConfig,
   NavMenuConfig,
+  PreviewConfig,
+  ResolvedPreview,
   AssetConfig,
   RoutingRule,
   ConceptDescriptor,

package/src/lib/sveltekit/content-routes.ts

@@ -16,8 +16,9 @@ import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest,
 import { isConflict } from '../github/types.js';
 import { log } from '../log/index.js';
 import { issueCsrfToken } from './csrf.js';
+import { requireSession } from './guard.js';
 import type { CookieJar, EventBase } from './types.js';
-import type { CairnRuntime, ConceptDescriptor, FrontmatterField } from '../content/types.js';
+import type { CairnRuntime, ConceptDescriptor, FrontmatterField, PreviewConfig, ResolvedPreview } from '../content/types.js';
 import type { Editor, Role } from '../auth/types.js';
 
 /** A sidebar concept entry: just enough to render the nav without shipping validators to the client. */
@@ -100,6 +101,10 @@ export interface EditData {
   publishedFlash: boolean;
   /** True after a discard redirect (`?discarded=1`), for the confirmation strip. */
   discardedFlash: boolean;
+  /** The adapter's preview knob resolved for this entry's concept (its `byConcept` override,
+   *  when one exists, applied over the top-level values); null when the site sets none, which
+   *  leaves the frame rendering unstyled markup behind a hint. */
+  preview: ResolvedPreview | null;
 }
 
 /** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
@@ -148,11 +153,17 @@ export interface RenameFailure {
  *  keys identify which guard refused. */
 export type ContentFormFailure = Partial<SaveFailure & DeleteRefusal & RenameFailure>;
 
-/** The signed-in editor the guard resolved, or a login redirect. Kept local to decouple event shapes. */
-function sessionOf(event: ContentEvent): Editor {
-  const editor = event.locals.editor;
-  if (!editor) throw redirect(303, '/admin/login');
-  return editor;
+/** Resolve the effective preview for one concept: its `byConcept` override wins per key, with
+ *  nullish coalescing so an override key that is present but undefined keeps the top-level value.
+ *  Stylesheets are always shared, and the `byConcept` map never reaches the client. */
+function resolvePreview(preview: PreviewConfig | undefined, conceptId: string): ResolvedPreview | null {
+  if (!preview) return null;
+  const override = preview.byConcept?.[conceptId];
+  return {
+    stylesheets: preview.stylesheets,
+    bodyClass: override?.bodyClass ?? preview.bodyClass,
+    containerClass: override?.containerClass ?? preview.containerClass,
+  };
 }
 
 /** Look up the concept named by the `[concept]` route param, or a 404. */
@@ -188,7 +199,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
   /** Layout load for every admin page: the nav, the user, the active path, the resolved theme,
    *  and the pending entries behind the topbar's publish-all action. */
   async function layoutLoad(event: ContentEvent): Promise<LayoutData> {
-    const editor = sessionOf(event);
+    const editor = requireSession(event);
     const cookieTheme = event.cookies?.get('cairn-admin-theme');
     const theme = cookieTheme === 'cairn-admin-dark' ? 'cairn-admin-dark' : 'cairn-admin';
     const cookieCollapsed = event.cookies?.get('cairn-admin-nav-collapsed');
@@ -282,7 +293,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
    *  with no manifest row appends a `new` row read from its branch. A listing failure degrades
    *  to an inline error, not a thrown 500. */
   async function listLoad(event: ContentEvent): Promise<ListData> {
-    sessionOf(event);
+    requireSession(event);
     const concept = conceptOf(runtime, event.params);
     const formError = event.url.searchParams.get('error');
     const publishedAllRaw = event.url.searchParams.get('publishedAll');
@@ -333,7 +344,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
 
   /** Create a new entry: validate the slug, compose a dated id when the concept is dated, refuse to clobber. */
   async function createAction(event: ContentEvent): Promise<never> {
-    sessionOf(event);
+    requireSession(event);
     const concept = conceptOf(runtime, event.params);
     const form = await event.request.formData();
     const slug = String(form.get('slug') ?? '').trim() || slugify(String(form.get('title') ?? ''));
@@ -378,7 +389,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
 
   /** Open a file for editing. A `?new=1` miss yields a blank document; any other miss is a 404. */
   async function editLoad(event: ContentEvent): Promise<EditData> {
-    sessionOf(event);
+    requireSession(event);
     const concept = conceptOf(runtime, event.params);
     const id = event.params.id ?? '';
     if (!isValidId(id)) throw error(400, 'Invalid entry id');
@@ -440,6 +451,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
       published,
       publishedFlash: event.url.searchParams.get('published') === '1',
       discardedFlash: event.url.searchParams.get('discarded') === '1',
+      preview: resolvePreview(runtime.preview, concept.id),
     };
   }
 
@@ -578,7 +590,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
   /** Save an edit: validate, then commit to the entry's pending branch with the session editor
    *  as author. Main and its manifest stay untouched until publish. Fails safe on 409. */
   async function saveAction(event: ContentEvent): Promise<ReturnType<typeof fail> | never> {
-    const editor = sessionOf(event);
+    const editor = requireSession(event);
     const concept = conceptOf(runtime, event.params);
     const id = event.params.id ?? '';
     // Confine the commit path to the concept dir, built from a validated id (the App token can
@@ -599,7 +611,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
    *  The branch is deleted only when its head still matches the commit this action made; a
    *  concurrent save moved it, so the entry stays pending and the next publish picks it up. */
   async function publishAction(event: ContentEvent): Promise<ReturnType<typeof fail> | never> {
-    const editor = sessionOf(event);
+    const editor = requireSession(event);
     const concept = conceptOf(runtime, event.params);
     const id = event.params.id ?? '';
     if (!isValidId(id)) throw error(400, 'Invalid entry id');
@@ -638,7 +650,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
    *  Mounted on the concept list shim, but the topbar posts here from anywhere, so the route's
    *  concept param is ignored and the redirect lands on the first configured concept. */
   async function publishAllAction(event: ContentEvent): Promise<never> {
-    const editor = sessionOf(event);
+    const editor = requireSession(event);
     const first = runtime.concepts[0];
     if (!first) throw error(404, 'No content types configured');
     const token = await mintToken(event.platform?.env ?? {});
@@ -725,7 +737,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
   /** Discard an entry's pending edits: delete the branch (tolerant of already-gone) and return to
    *  the edit page when the entry lives on main, else to the list (the entry is gone entirely). */
   async function discardAction(event: ContentEvent): Promise<never> {
-    const editor = sessionOf(event);
+    const editor = requireSession(event);
     const concept = conceptOf(runtime, event.params);
     const id = event.params.id ?? '';
     if (!isValidId(id)) throw error(400, 'Invalid entry id');
@@ -806,7 +818,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
 
   /** Delete an entry from its editor. The id comes from the route param. */
   async function deleteAction(event: ContentEvent): Promise<ReturnType<typeof fail> | never> {
-    const editor = sessionOf(event);
+    const editor = requireSession(event);
     const concept = conceptOf(runtime, event.params);
     const id = event.params.id ?? '';
     if (!isValidId(id)) throw error(400, 'Invalid entry id');
@@ -815,7 +827,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
 
   /** Delete an entry from the concept list. The id comes from the form body. */
   async function listDeleteAction(event: ContentEvent): Promise<ReturnType<typeof fail> | never> {
-    const editor = sessionOf(event);
+    const editor = requireSession(event);
     const concept = conceptOf(runtime, event.params);
     const form = await event.request.formData();
     const id = String(form.get('id') ?? '');
@@ -828,7 +840,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
    *  are the authoritative gate. The same last-writer-wins manifest race as save and delete applies,
    *  caught by the build's fail-closed backstop. */
   async function renameAction(event: ContentEvent): Promise<ReturnType<typeof fail> | never> {
-    const editor = sessionOf(event);
+    const editor = requireSession(event);
     const concept = conceptOf(runtime, event.params);
     const id = event.params.id ?? '';
     if (!isValidId(id)) throw error(400, 'Invalid entry id');

package/src/lib/sveltekit/guard.ts

@@ -93,8 +93,10 @@ export function createAuthGuard() {
   };
 }
 
-/** For a protected load/action: the session the guard already resolved, or a login redirect. */
-export function requireSession(event: RequestContext): Editor {
+/** For a protected load/action: the session the guard already resolved, or a login redirect.
+ *  The parameter is the minimal structural need (just `locals`), so every engine event shape
+ *  (RequestContext, the content routes' ContentEvent) and a real RequestEvent all satisfy it. */
+export function requireSession(event: { locals: { editor?: Editor | null } }): Editor {
   const editor = event.locals.editor;
   if (!editor) throw redirect(303, '/admin/login');
   return editor;

package/src/lib/sveltekit/nav-routes.ts

@@ -8,9 +8,9 @@ import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
 import { isConflict } from '../github/types.js';
 import { log } from '../log/index.js';
 import { parseSiteConfig, extractMenu, validateNavTree, setMenu, type NavNode } from '../nav/site-config.js';
+import { requireSession } from './guard.js';
 import type { CairnRuntime } from '../content/types.js';
 import type { ContentEvent } from './content-routes.js';
-import type { Editor } from '../auth/types.js';
 
 /** One page option for the URL picker datalist. */
 export interface NavPageOption {
@@ -34,13 +34,6 @@ export interface NavRoutesDeps {
   mintToken?: (env: GithubKeyEnv) => string | Promise<string>;
 }
 
-/** The signed-in editor the guard resolved, or a login redirect. */
-function sessionOf(event: ContentEvent): Editor {
-  const editor = event.locals.editor;
-  if (!editor) throw redirect(303, '/admin/login');
-  return editor;
-}
-
 export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {}) {
   const mintToken =
     deps.mintToken ?? ((env: GithubKeyEnv) => cachedInstallationToken(appCredentials(runtime.backend, env)));
@@ -63,7 +56,7 @@ export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {})
 
   /** Load the nav editor. A missing or unparsable config degrades to an empty tree so it still opens. */
   async function navLoad(event: ContentEvent): Promise<NavLoadData> {
-    sessionOf(event);
+    requireSession(event);
     const config = runtime.navMenu;
     if (!config) throw error(404, 'No navigation menu configured');
     const maxDepth = config.maxDepth ?? 2;
@@ -109,7 +102,7 @@ export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {})
 
   /** Save the nav tree: validate, then read-modify-commit the one menu with the session editor as author. */
   async function navSave(event: ContentEvent): Promise<never> {
-    const editor = sessionOf(event);
+    const editor = requireSession(event);
     const config = runtime.navMenu;
     if (!config) throw error(404, 'No navigation menu configured');
     const maxDepth = config.maxDepth ?? 2;

package/src/lib/vite/index.ts

@@ -61,21 +61,17 @@ export const result = ${resultExpr};
 `;
 }
 
-/** Evaluate the virtual module in the given mode inside the consumer's own Vite resolution, then
- *  return the module's `result`. It reuses the consumer's loaded config (so `$lib`, the config
- *  module, `import.meta.glob`, and `?raw` resolve exactly as the build does) and strips the
- *  cairnManifest plugin from the nested server's plugin list, so its buildStart never recurses.
- *  This runs at build time and in the bin, never in the request lifecycle. */
-async function evalVirtual(
-  opts: CairnManifestOptions,
-  mode: 'verify' | 'write',
-  root: string,
-): Promise<string> {
+/** Evaluate a virtual module source inside the consumer's own Vite resolution, then return the
+ *  module's `result`. It reuses the consumer's loaded config (so `$lib`, the config module,
+ *  `import.meta.glob`, and `?raw` resolve exactly as the build does) and strips the cairnManifest
+ *  plugin from the nested server's plugin list, so its buildStart never recurses. This runs at
+ *  build time and in the bins, never in the request lifecycle. */
+async function evalVirtual(source: string, root: string): Promise<string> {
   const { createServer, loadConfigFromFile } = await import('vite');
   // Load the consumer's real Vite config so the nested server inherits SvelteKit's resolution
   // (the $lib alias, the app root, the ?raw and import.meta.glob handling). Drop cairnManifest from
   // it so the nested server's buildStart does not recurse, and add a plugin that serves only the
-  // virtual module in the requested mode.
+  // given virtual module source.
   const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, undefined, root);
   const inlineConfig = loaded?.config ?? {};
   const server = await createServer({
@@ -84,7 +80,7 @@ async function evalVirtual(
     configFile: false,
     logLevel: 'silent',
     server: { middlewareMode: true, hmr: false, watch: null },
-    plugins: [...stripCairnManifest(inlineConfig.plugins ?? []), cairnVirtualOnly(opts, mode)],
+    plugins: [...stripCairnManifest(inlineConfig.plugins ?? []), cairnVirtualOnly(source)],
   });
   try {
     const mod = (await server.ssrLoadModule(VIRTUAL_ID)) as { result: string };
@@ -115,13 +111,13 @@ export function stripCairnManifest(plugins: PluginOption | PluginOption[]): Plug
 /** Verify the committed manifest against the corpus from a Vite context, throwing on drift. The bin
  *  and the plugin share this; the spike proved it runs cleanly inside the consumer's config. */
 export async function verifyManifestFromVite(opts: CairnManifestOptions, root: string): Promise<void> {
-  await evalVirtual(opts, 'verify', root);
+  await evalVirtual(virtualSource(opts, 'verify'), root);
 }
 
 /** Regenerate the serialized manifest from the corpus in a Vite context, sharing the build's
  *  resolution. The cairn-manifest bin (a later task) will call this and write the result. */
 export async function buildManifestFromVite(opts: CairnManifestOptions, root: string): Promise<string> {
-  return evalVirtual(opts, 'write', root);
+  return evalVirtual(virtualSource(opts, 'write'), root);
 }
 
 /** The cairnManifest plugin. It serves the verify virtual module to the app graph and, in
@@ -198,16 +194,74 @@ function findCairnOptions(plugins: unknown): CairnManifestOptions | null {
   return null;
 }
 
-/** A minimal plugin that serves only the virtual module in one mode, for the nested SSR load. It
+/** A minimal plugin that serves only the given virtual module source, for the nested SSR load. It
  *  carries no buildStart, so the nested server never recurses into the verify. */
-function cairnVirtualOnly(opts: CairnManifestOptions, mode: 'verify' | 'write'): Plugin {
+function cairnVirtualOnly(source: string): Plugin {
   return {
     name: 'cairn-manifest-virtual',
     resolveId(id) {
       if (id === VIRTUAL_ID) return RESOLVED_ID;
     },
     load(id) {
-      if (id === RESOLVED_ID) return virtualSource(opts, mode);
+      if (id === RESOLVED_ID) return source;
     },
   };
 }
+
+/** The repo and sender facts cairn-doctor derives off the consumer's adapter. */
+export interface AdapterFacts {
+  /** `cairn.backend.owner`. */
+  owner?: string;
+  /** `cairn.backend.repo`. */
+  repo?: string;
+  /** `cairn.sender.from`. */
+  from?: string;
+}
+
+/** Build the virtual module that reads only the adapter facts the doctor derives. It imports the
+ *  configured config module and exports the string-typed `owner`, `repo`, and `from` as JSON, so
+ *  nothing else of the adapter (least of all a secret) crosses the boundary. */
+function adapterFactsSource(opts: CairnManifestOptions): string {
+  return `
+import { cairn } from ${JSON.stringify(opts.configModule)};
+const backend = cairn?.backend ?? {};
+const sender = cairn?.sender ?? {};
+const facts = {};
+if (typeof backend.owner === 'string') facts.owner = backend.owner;
+if (typeof backend.repo === 'string') facts.repo = backend.repo;
+if (typeof sender.from === 'string') facts.from = sender.from;
+export const result = JSON.stringify(facts);
+`;
+}
+
+/** Read `{ owner, repo, from }` off the consumer's adapter by evaluating a tiny virtual module
+ *  through the consumer's own Vite resolution, the same machinery the cairn-manifest bin uses.
+ *  cairn-doctor calls this to fill inputs the operator did not pass. Derivation is best-effort:
+ *  any failure (no Vite config, no cairnManifest plugin, a config module that throws) returns
+ *  null, so the doctor degrades to flags instead of crashing. This runs only on the bin path,
+ *  never in a Worker. */
+export async function readAdapterFacts(cwd: string = process.cwd()): Promise<AdapterFacts | null> {
+  try {
+    const { loadConfigFromFile } = await import('vite');
+    const loaded = await loadConfigFromFile(
+      { command: 'build', mode: 'production' },
+      undefined,
+      cwd,
+      'silent',
+    );
+    if (!loaded) return null;
+    const opts = findCairnOptions(loaded.config.plugins);
+    if (!opts) return null;
+    const parsed = JSON.parse(await evalVirtual(adapterFactsSource(opts), cwd)) as Record<
+      string,
+      unknown
+    >;
+    const facts: AdapterFacts = {};
+    if (typeof parsed.owner === 'string') facts.owner = parsed.owner;
+    if (typeof parsed.repo === 'string') facts.repo = parsed.repo;
+    if (typeof parsed.from === 'string') facts.from = parsed.from;
+    return facts;
+  } catch {
+    return null;
+  }
+}