@inneropen/marvin-astro 1.1.1 → 1.2.1

package/src/renderers/validation.ts

@@ -0,0 +1,55 @@
+import type { RendererRegistry } from './types.js';
+import type { MissingRenderer, ValidationResult } from './validation-types.js';
+
+interface EntryTypeWithRendering {
+  slug: string;
+  name: string;
+  isRendered?: boolean;
+  rendering?: Record<string, unknown> | null;
+}
+
+function isRendererRegistry(value: unknown): value is RendererRegistry {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as RendererRegistry).has === 'function'
+  );
+}
+
+export function validateRenderers(
+  entryTypes: EntryTypeWithRendering[],
+  registry: RendererRegistry | Record<string, unknown>,
+  options?: { ignore?: string[] }
+): ValidationResult {
+  const ignore = new Set(options?.ignore ?? []);
+
+  const withRenderer = entryTypes.filter(
+    (et) => et.isRendered && et.rendering?.renderer && !ignore.has(et.slug)
+  );
+
+  const hasRenderer = isRendererRegistry(registry)
+    ? (name: string) => registry.has(name)
+    : (name: string) => name in registry;
+
+  const missing: MissingRenderer[] = [];
+
+  for (const et of withRenderer) {
+    const rendering = et.rendering!;
+    const renderer = rendering.renderer as string;
+    if (!hasRenderer(renderer)) {
+      missing.push({
+        entryTypeSlug: et.slug,
+        entryTypeName: et.name,
+        renderer,
+        package: (rendering.package as string) ?? undefined,
+        version: (rendering.version as string) ?? undefined,
+      });
+    }
+  }
+
+  return {
+    total: withRenderer.length,
+    covered: withRenderer.length - missing.length,
+    missing,
+  };
+}

package/src/repository.ts

@@ -0,0 +1,206 @@
+/**
+ * The repository factory.
+ *
+ * `getAll` / `getBySlug` / `getFeatured` is the same forty lines of try / fallback / memoize
+ * around every content type on every site. Only the transform differs. This holds the forty
+ * lines; the site writes the transform.
+ */
+
+import { errorMessage } from './client.js';
+import { createFieldAccessor, type FieldAccessor } from './fields.js';
+import { isFullEntry, type MarvinFetcher } from './fetch.js';
+import type { MarkdownRenderer } from './markdown.js';
+import type { MarvinContentEntry } from './types.js';
+
+export type RepositoryOptions<T> = {
+  /** Collection slug to load from. */
+  collection?: string;
+  /**
+   * Collection slugs tried in order; the first one that yields entries wins. Lets a site work
+   * against workspaces that named the same thing `bench-notes`, `journal`, or `blog`.
+   */
+  collections?: string[];
+  /**
+   * Fetch each list item as a full entry before transforming.
+   *
+   * The collection endpoint returns `PublishedEntryListItem`, which has no `assets[]` or
+   * `resources[]` (only their slugs) and, on older servers, no `data_json`; the single-entry
+   * endpoint returns `PublishedEntryRead`, which has all of it. So if the transform reads asset
+   * roles, resources, or (on an older server) any schema field, this must be `true`. It costs one
+   * request per entry. `bySlug` always works from full entries either way.
+   */
+  hydrate?: boolean;
+  /** Build the resolved item from an entry. May be async (e.g. to render markdown). */
+  transform: (entry: MarvinContentEntry, fields: FieldAccessor) => T | Promise<T>;
+  /** Static data to serve when Marvin is unreachable or the collection is empty. */
+  fallback?: () => T[] | Promise<T[]>;
+  /** Applied to Marvin and fallback results alike, so ordering doesn't depend on the source. */
+  sort?: (a: T, b: T) => number;
+  /** Applied to Marvin and fallback results alike. */
+  filter?: (item: T) => boolean;
+  /** The route an entry resolves to; exposed to the transform as `fields.href`. */
+  href?: (slug: string, entry: MarvinContentEntry) => string;
+  /** How to read an item's slug for `bySlug`. Defaults to `item.slug`. */
+  slugOf?: (item: T) => string | undefined;
+  /** How to tell whether an item is featured. Defaults to `item.featured`. */
+  isFeatured?: (item: T) => boolean;
+};
+
+export type Repository<T> = {
+  /** Every item, resolved once per process. */
+  all(): Promise<T[]>;
+  /**
+   * One item by slug. Served from `all()` once that has loaded; otherwise a direct entry
+   * fetch, falling back to a scan of `all()`.
+   */
+  bySlug(slug: string): Promise<T | undefined>;
+  /** The first featured item, or the first item when none is marked. */
+  featured(): Promise<T | undefined>;
+  /** Every featured item, in `all()` order. */
+  allFeatured(): Promise<T[]>;
+  /** Drop the memoized results. Next call re-fetches. */
+  reset(): void;
+};
+
+export type RepositoryContext = {
+  fetcher: MarvinFetcher;
+  renderMarkdown: MarkdownRenderer;
+};
+
+function defaultSlugOf<T>(item: T): string | undefined {
+  const slug = (item as { slug?: unknown }).slug;
+  return typeof slug === 'string' ? slug : undefined;
+}
+
+function defaultIsFeatured<T>(item: T): boolean {
+  return Boolean((item as { featured?: unknown }).featured);
+}
+
+export function createRepository<T>(
+  context: RepositoryContext,
+  options: RepositoryOptions<T>
+): Repository<T> {
+  const { fetcher, renderMarkdown } = context;
+  const collections = options.collections ?? (options.collection ? [options.collection] : []);
+  const slugOf = options.slugOf ?? defaultSlugOf;
+  const isFeatured = options.isFeatured ?? defaultIsFeatured;
+
+  /** The loaded list, plus the slugs whose items were built from full entries. */
+  type Loaded = { items: T[]; fromFullEntry: Set<string> };
+  let loadedPromise: Promise<Loaded> | null = null;
+  let allPromise: Promise<T[]> | null = null;
+  const bySlugCache = new Map<string, Promise<T | undefined>>();
+
+  function arrange(items: T[]): T[] {
+    const filtered = options.filter ? items.filter(options.filter) : items;
+    return options.sort ? [...filtered].sort(options.sort) : filtered;
+  }
+
+  function transform(entry: MarvinContentEntry, collection?: string): Promise<T> {
+    const slug = (entry as { slug?: string }).slug ?? '';
+    const fields = createFieldAccessor(entry, {
+      renderMarkdown,
+      href: options.href?.(slug, entry),
+      collection,
+    });
+    return Promise.resolve(options.transform(entry, fields));
+  }
+
+  async function useFallback(): Promise<Loaded> {
+    return { items: arrange((await options.fallback?.()) ?? []), fromFullEntry: new Set() };
+  }
+
+  async function load(): Promise<Loaded> {
+    if (collections.length > 0 && fetcher.backend.hasBackend()) {
+      try {
+        const entries = options.hydrate
+          ? await fetcher.hydratedCollectionEntriesFallback(collections)
+          : await fetcher.collectionEntriesFallback(collections);
+
+        if (entries.length > 0) {
+          const items = await Promise.all(entries.map((entry) => transform(entry)));
+          const fromFullEntry = new Set<string>();
+          items.forEach((item, index) => {
+            const slug = slugOf(item);
+            if (slug !== undefined && isFullEntry(entries[index])) fromFullEntry.add(slug);
+          });
+          return { items: arrange(items), fromFullEntry };
+        }
+      } catch (error) {
+        fetcher.backend.remember(error);
+        fetcher.backend.warn(
+          `Collection "${collections[0]}" failed, using fallback: ${errorMessage(error)}`
+        );
+      }
+    }
+
+    return useFallback();
+  }
+
+  function findInList(items: T[], slug: string): T | undefined {
+    return items.find((item) => slugOf(item) === slug);
+  }
+
+  async function loadBySlug(slug: string): Promise<T | undefined> {
+    // Once a hydrated list has loaded, every slug in it is already transformed from a full entry —
+    // a per-entry fetch would be a second request for the same content (~1.4s per detail page on
+    // a 280-entry site). An item built from a bare list item is NOT served: it has no assets[] or
+    // resources[], so a detail page would lose its role-picked images and resource links.
+    let listed: T | undefined;
+    if (loadedPromise) {
+      const loaded = await loadedPromise;
+      listed = findInList(loaded.items, slug);
+      if (listed && loaded.fromFullEntry.has(slug)) return listed;
+    }
+
+    if (fetcher.backend.hasBackend()) {
+      try {
+        const entry = await fetcher.entry(slug);
+        if (entry) return await transform(entry);
+      } catch (error) {
+        fetcher.backend.remember(error);
+        fetcher.backend.warn(`Entry "${slug}" failed, using fallback: ${errorMessage(error)}`);
+      }
+    }
+
+    // No backend, no such entry, or a transform that blew up: fall back to the resolved list,
+    // which is either Marvin's or the static data — the caller doesn't need to care which.
+    return listed ?? findInList(await all(), slug);
+  }
+
+  function all(): Promise<T[]> {
+    if (!allPromise) {
+      loadedPromise = load();
+      allPromise = loadedPromise.then((loaded) => loaded.items);
+    }
+    return allPromise;
+  }
+
+  return {
+    all,
+
+    bySlug(slug: string): Promise<T | undefined> {
+      let cached = bySlugCache.get(slug);
+      if (!cached) {
+        cached = loadBySlug(slug);
+        bySlugCache.set(slug, cached);
+      }
+      return cached;
+    },
+
+    async allFeatured(): Promise<T[]> {
+      return (await all()).filter(isFeatured);
+    },
+
+    async featured(): Promise<T | undefined> {
+      const items = await all();
+      return items.find(isFeatured) ?? items[0];
+    },
+
+    reset() {
+      allPromise = null;
+      loadedPromise = null;
+      bySlugCache.clear();
+    },
+  };
+}

package/src/sections.ts

@@ -0,0 +1,39 @@
+import { entryEmbeds } from './embeds.js';
+import type { MarvinFetcher } from './fetch.js';
+import { createMarkdownRenderer, preserveSoftBreaks, type MarkdownRenderer } from './markdown.js';
+import { asString, assetUrl, entryField, selectAssetByRole } from './normalize.js';
+import type { SectionLanding } from './types.js';
+
+export type SectionLandingOptions = {
+  /** Asset role to use as the hero image. Default `'hero'`. */
+  heroRole?: string;
+  /** Field holding the intro copy. Default `'body'`, falling back to the entry summary. */
+  bodyField?: string;
+};
+
+/**
+ * Resolve a section-landing header from a Marvin `page` entry with the given slug.
+ *
+ * The intro is rendered with authored line breaks preserved — landing copy is written as a few
+ * deliberate lines, not a soft-wrapped paragraph, and losing those breaks changes the layout.
+ */
+export async function loadSectionLanding(
+  fetcher: MarvinFetcher,
+  slug: string,
+  renderMarkdown: MarkdownRenderer = createMarkdownRenderer(),
+  options: SectionLandingOptions = {}
+): Promise<SectionLanding> {
+  const entry = await fetcher.entry(slug);
+  if (!entry) return {};
+
+  const source =
+    asString(entryField(entry, options.bodyField ?? 'body')) ?? asString(entry.summary);
+
+  return {
+    title: asString(entry.title),
+    introHtml: source
+      ? await renderMarkdown(preserveSoftBreaks(source), { embeds: entryEmbeds(entry) })
+      : undefined,
+    hero: assetUrl(selectAssetByRole(entry, options.heroRole ?? 'hero')),
+  };
+}

package/src/site.ts

@@ -0,0 +1,222 @@
+/**
+ * Site identity + SEO.
+ *
+ * Marvin's site configuration is optional almost everywhere; a template that had to guard every
+ * field would be unreadable. This resolves it once into an `ApiSite` where title, description,
+ * siteName, locale and timezone are always present, and where brand asset slugs have already
+ * become URLs.
+ */
+
+import type { MarvinSite, SiteConfiguration } from '@inneropen/marvin-sdk';
+import { siteEmbeds } from './embeds.js';
+import type { MarvinFetcher } from './fetch.js';
+import { asRecord, asString, assetUrl } from './normalize.js';
+import type { ApiSeo, ApiSite } from './types.js';
+
+export type SiteOptions = {
+  /**
+   * Static identity to fall back to, field by field, when Marvin is unreachable or leaves a
+   * value unset. Anything omitted here falls through to a neutral default.
+   */
+  fallback?: Partial<ApiSite> | (() => Partial<ApiSite>);
+  /** Default locale when neither Marvin nor the fallback sets one. Default `'en-US'`. */
+  defaultLocale?: string;
+  /** Default timezone when neither Marvin nor the fallback sets one. Default `'UTC'`. */
+  defaultTimezone?: string;
+};
+
+/**
+ * Build resolved SEO from Marvin's raw SiteSeo block, applying identity fallbacks so title,
+ * description and siteName are never empty. Absent → sensible defaults (robots `index,follow`;
+ * og type `website`; large-image Twitter card).
+ */
+export function buildSeo(
+  raw: Record<string, unknown> | undefined,
+  identity: { title: string; description: string; canonicalUrl?: string; siteName: string }
+): ApiSeo {
+  const seo = raw ?? {};
+  const verification = asRecord(seo.verification);
+
+  return {
+    title: asString(seo.title) ?? identity.title,
+    titleTemplate: asString(seo.titleTemplate),
+    description: asString(seo.description) ?? identity.description,
+    keywords: Array.isArray(seo.keywords)
+      ? seo.keywords.filter((keyword): keyword is string => typeof keyword === 'string')
+      : [],
+    robots: asString(seo.robots) ?? 'index,follow',
+    image: asString(seo.image),
+    imageAlt: asString(seo.imageAlt),
+    ogType: asString(seo.ogType) ?? 'website',
+    siteName: asString(seo.siteName) ?? identity.siteName,
+    twitterCard: asString(seo.twitterCard) ?? 'summary_large_image',
+    twitterHandle: asString(seo.twitterHandle),
+    twitterCreator: asString(seo.twitterCreator),
+    fbAppId: asString(seo.fbAppId),
+    themeColor: asString(seo.themeColor),
+    publisher: asString(seo.publisher),
+    canonicalUrl: identity.canonicalUrl,
+    verification: {
+      google: asString(verification.google),
+      bing: asString(verification.bing),
+      pinterest: asString(verification.pinterest),
+      yandex: asString(verification.yandex),
+    },
+  };
+}
+
+function normalizeSocial(social: unknown): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(asRecord(social)).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1].length > 0
+    )
+  );
+}
+
+/** The offline site: the caller's fallback, with neutral defaults under it. */
+export function buildFallbackSite(options: SiteOptions = {}): ApiSite {
+  const provided = typeof options.fallback === 'function' ? options.fallback() : options.fallback;
+  const fallback = provided ?? {};
+  const title = fallback.title ?? fallback.name ?? 'Untitled site';
+  const description = fallback.description ?? '';
+
+  return {
+    ...fallback,
+    name: fallback.name ?? title,
+    title,
+    description,
+    locale: fallback.locale ?? options.defaultLocale ?? 'en-US',
+    timezone: fallback.timezone ?? options.defaultTimezone ?? 'UTC',
+    social: fallback.social ?? {},
+    metadata: fallback.metadata ?? {},
+    seo:
+      fallback.seo ??
+      buildSeo(undefined, { title, description, siteName: fallback.name ?? title }),
+  };
+}
+
+function transformMarvinSite(marvinSite: MarvinSite, fallback: ApiSite): ApiSite {
+  const config: SiteConfiguration = marvinSite.site;
+  const metadata = asRecord(config.metadataJson);
+  const title =
+    asString(config.title) ?? asString(marvinSite.workspace?.name) ?? fallback.title;
+  const description = asString(config.description) ?? fallback.description;
+
+  return {
+    workspaceSlug: asString(marvinSite.workspace?.slug),
+    workspaceName: asString(marvinSite.workspace?.name),
+    name: title,
+    title,
+    tagline: asString(config.tagline) ?? fallback.tagline,
+    description,
+    canonicalUrl: asString(config.canonicalUrl) ?? fallback.canonicalUrl,
+    logo: asString(config.logo) ?? fallback.logo,
+    favicon: asString(config.favicon) ?? fallback.favicon,
+    locale: asString(config.locale) ?? fallback.locale,
+    timezone: asString(config.timezone) ?? fallback.timezone,
+    email: asString(config.contactEmail) ?? fallback.email,
+    imprint: asString(metadata.imprint) ?? fallback.imprint,
+    social: { ...fallback.social, ...normalizeSocial(config.social) },
+    // Typed `config.seo` when the SDK declares it, else the raw `metadata.seo` blob — older
+    // SDKs drop the typed field but pass the blob through untouched, and workspaces configured
+    // before the typed field existed still only have the blob.
+    seo: buildSeo(asRecord((config as { seo?: unknown }).seo ?? metadata.seo), {
+      title,
+      description,
+      canonicalUrl: asString(config.canonicalUrl),
+      siteName: title,
+    }),
+    // Older servers and SDKs don't send it; `siteEmbeds` returns undefined then.
+    embeds: siteEmbeds(
+      (config as { embeds?: unknown }).embeds ?? (marvinSite as { embeds?: unknown }).embeds
+    ),
+    metadata,
+  };
+}
+
+function looksLikeAssetSlug(value: string): boolean {
+  return !/^https?:\/\//.test(value) && !value.startsWith('/') && !value.startsWith('data:');
+}
+
+export type SiteLoader = {
+  get(): Promise<ApiSite>;
+  reset(): void;
+};
+
+export function createSiteLoader(fetcher: MarvinFetcher, options: SiteOptions = {}): SiteLoader {
+  const fallback = buildFallbackSite(options);
+  let promise: Promise<ApiSite> | null = null;
+
+  async function resolveAssetSlug(slug: string | undefined): Promise<string | undefined> {
+    if (!slug) return undefined;
+    return assetUrl(await fetcher.asset(slug));
+  }
+
+  // Resolve a value only when it looks like a bare asset slug; a URL/path/data URI (or a slug with
+  // no matching asset) is returned unchanged.
+  async function resolveMaybeSlug(value: string | undefined): Promise<string | undefined> {
+    if (!value || !looksLikeAssetSlug(value)) return value;
+    return (await resolveAssetSlug(value)) ?? value;
+  }
+
+  async function load(): Promise<ApiSite> {
+    const marvinSite = await fetcher.site();
+    if (!marvinSite) return fallback;
+
+    const site = transformMarvinSite(marvinSite, fallback);
+
+    // Brand-asset registry: resolve EVERY `brand.<name>` slug → URL in one pass. A site adds a
+    // shared asset with one config line (`brand.paperFold = "paper-fold"`) plus an upload;
+    // components then read `site.brand.paperFold`. No code change per asset.
+    const brandPairs = Object.entries(asRecord(site.metadata.brand)).filter(
+      (entry): entry is [string, string] =>
+        typeof entry[1] === 'string' && entry[1].trim().length > 0
+    );
+    const resolved = await Promise.all(
+      brandPairs.map(async ([name, slug]) => [name, await resolveAssetSlug(slug)] as const)
+    );
+    const brand: Record<string, string> = {};
+    const brandBySlug = new Map<string, string>();
+    for (const [index, [name, url]] of resolved.entries()) {
+      if (!url) continue;
+      brand[name] = url;
+      brandBySlug.set(brandPairs[index][1], url);
+    }
+
+    // The og:image may be given as a bare asset slug too. It is usually one of the brand slugs
+    // (a monogram, a logo), so check what was just resolved before fetching it again.
+    const rawImage = site.seo.image;
+    const ogImage =
+      rawImage && looksLikeAssetSlug(rawImage)
+        ? (brandBySlug.get(rawImage) ?? (await resolveAssetSlug(rawImage)))
+        : undefined;
+
+    // The top-level `site_logo` / `site_favicon` fields may be bare asset slugs too (like brand.*
+    // and og:image) — resolve them so they can reference an uploaded asset by slug. The brand-map
+    // aliases still win when present.
+    const logo = brand.logo ?? (await resolveMaybeSlug(site.logo));
+    const favicon = brand.favicon ?? (await resolveMaybeSlug(site.favicon));
+
+    return {
+      ...site,
+      brand,
+      // Convenience aliases for common callers; all of these also live in `site.brand`.
+      logo,
+      favicon,
+      seal: brand.seal ?? site.seal,
+      seo: { ...site.seo, image: ogImage ?? site.seo.image },
+    };
+  }
+
+  return {
+    get() {
+      // Memoized: components like a per-card brand stamp render many instances per page, so
+      // this keeps brand-slug resolution to once per process rather than once per render.
+      promise ??= load();
+      return promise;
+    },
+    reset() {
+      promise = null;
+    },
+  };
+}