ferst-core 0.7.13 → 0.8.1

package/lib/seo.mjs

@@ -0,0 +1,130 @@
+/**
+ * Search signals every Ferst site gives search engines: one canonical address per page, a
+ * sitemap, robots.txt, and test copies kept out of search results. Pure helpers, shared by
+ * the ferst() integration (build time, Node) and its injected routes.
+ *
+ * The site's public address comes from `ferst-site.json` `siteUrl` (the platform sets it
+ * at setup and when the domain changes), or the `FERST_SITE_URL` env var. Without one, no
+ * address is guessed: canonical links and the sitemap need absolute addresses, so they're
+ * left out rather than pointed at a wrong host.
+ *
+ * Live site vs test copy: the production branch (`main`, or `productionBranch`) is the live
+ * site; any other branch's deploy is a test copy, the same rule the CMS uses to pick its
+ * git-proxy. A test copy is marked noindex everywhere (an `X-Robots-Tag` header on every
+ * file, and a robots meta on every page) while crawling stays allowed: an engine has to
+ * fetch a page to see its noindex.
+ */
+
+/**
+ * An address's origin (`https://host`), or null when it isn't a web address. A bare host
+ * gets https; any path or query is dropped, since it would make every canonical wrong.
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function normaliseSiteUrl(value) {
+  if (typeof value !== 'string') return null;
+  const raw = value.trim();
+  if (!raw) return null;
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`;
+  let url;
+  try {
+    url = new URL(withScheme);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
+  if (!url.hostname.includes('.') && url.hostname !== 'localhost') return null;
+  return url.origin;
+}
+
+/**
+ * The site's address and whether this build is the live site.
+ * @param {{ siteMeta?: { siteUrl?: string, productionBranch?: string } | null, branch: string, env?: Record<string, string | undefined> }} p
+ * @returns {{ siteUrl: string | null, production: boolean }}
+ */
+export function seoContext({ siteMeta, branch, env = {} }) {
+  const siteUrl = normaliseSiteUrl(env.FERST_SITE_URL || siteMeta?.siteUrl);
+  const prodFromMeta = typeof siteMeta?.productionBranch === 'string' ? siteMeta.productionBranch.trim() : '';
+  const productionBranch = (env.FERST_PROD_BRANCH || prodFromMeta || 'main').trim();
+  return { siteUrl, production: branch === productionBranch };
+}
+
+/**
+ * A page's canonical address: the site's origin plus the path it's served at. Pages are
+ * folders (`/clergy/` serves `clergy/index.html`), so a page path gets a trailing slash; a
+ * file path (`/uploads/x.pdf`) is left as it is. Any query string is dropped.
+ * @param {string} siteUrl
+ * @param {string} pathname
+ */
+export function canonicalUrl(siteUrl, pathname) {
+  let path = String(pathname || '/').split(/[?#]/)[0] || '/';
+  if (!path.startsWith('/')) path = `/${path}`;
+  const last = path.split('/').pop() ?? '';
+  const isFile = /\.[a-z0-9]{1,5}$/i.test(last);
+  if (!isFile && !path.endsWith('/')) path = `${path}/`;
+  return `${siteUrl}${path}`;
+}
+
+/**
+ * robots.txt. The live site allows everything and names its sitemap. A test copy also
+ * allows crawling (its pages carry noindex, which engines only see by fetching them) and
+ * names no sitemap.
+ * @param {{ siteUrl: string | null, production: boolean }} p
+ */
+export function robotsTxt({ siteUrl, production }) {
+  if (!production) {
+    return [
+      '# A test copy: every page and file is marked noindex, so search engines leave it out.',
+      '# Crawling stays allowed, or they could not see that noindex.',
+      'User-agent: *',
+      'Allow: /',
+      '',
+    ].join('\n');
+  }
+  const lines = ['User-agent: *', 'Allow: /'];
+  if (siteUrl) lines.push('', `Sitemap: ${siteUrl}/sitemap.xml`);
+  return `${lines.join('\n')}\n`;
+}
+
+const XML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' };
+const xmlEscape = (s) => String(s).replace(/[&<>"']/g, (c) => XML_ESCAPES[c]);
+
+/**
+ * A sitemap (sitemaps.org protocol): each address once, with a last-modified date where known.
+ * @param {Array<{ loc: string, lastmod?: Date | string }>} entries
+ */
+export function sitemapXml(entries) {
+  const seen = new Set();
+  const urls = [];
+  for (const { loc, lastmod } of entries) {
+    if (!loc || seen.has(loc)) continue;
+    seen.add(loc);
+    let date = '';
+    if (lastmod) {
+      const d = lastmod instanceof Date ? lastmod : new Date(lastmod);
+      if (!Number.isNaN(d.getTime())) date = d.toISOString().slice(0, 10);
+    }
+    urls.push(`  <url><loc>${xmlEscape(loc)}</loc>${date ? `<lastmod>${date}</lastmod>` : ''}</url>`);
+  }
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    ...urls,
+    '</urlset>',
+    '',
+  ].join('\n');
+}
+
+const NOINDEX_RULE = '/*\n  X-Robots-Tag: noindex\n';
+
+/**
+ * A Cloudflare Pages `_headers` file that marks every path noindex (pages and files such as
+ * PDFs alike), keeping any headers the site already sets. Idempotent.
+ * @param {string} existing
+ */
+export function withNoindexHeader(existing) {
+  const current = String(existing ?? '');
+  if (/X-Robots-Tag:\s*noindex/i.test(current)) return current;
+  if (!current.trim()) return NOINDEX_RULE;
+  return `${current.replace(/\s*$/, '')}\n\n${NOINDEX_RULE}`;
+}

package/lib/site-icon.mjs

@@ -0,0 +1,145 @@
+/**
+ * The site's browser icon, written into every build by the ferst() integration:
+ * `/favicon.ico` (32 and 48 px, as PNGs inside the .ico, which every current browser
+ * reads) and `/apple-touch-icon.png` (180 px, opaque, for phones' home screens). Base links
+ * both. A migrated site's old `/favicon.ico` address keeps working this way too.
+ *
+ * Where the icon comes from, first match wins:
+ *   1. the browser icon set in the CMS (logoSettings `favicon`);
+ *   2. the site's header logo, when it's roughly square (a wide wordmark would shrink to an
+ *      unreadable strip);
+ *   3. the site's initial, in white on its brand colour (or in ink on a light brand colour).
+ * A site's own `public/favicon.ico` or `public/apple-touch-icon.png` is never overwritten.
+ * Drawing needs `sharp` (installed with Astro). Without it the build goes on with a warning.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+/** A logo counts as square when its width over height is within these bounds. */
+const SQUARE = [0.8, 1.25];
+
+/** The first letter (or digit) of the site's name, upper case; '' when there's none. */
+export function initialOf(name) {
+  const m = String(name ?? '').match(/[\p{L}\p{N}]/u);
+  return m ? m[0].toLocaleUpperCase('en-GB') : '';
+}
+
+/** Relative luminance of a #rrggbb colour (0 dark … 1 light); null when it isn't one. */
+function luminance(hex) {
+  const m = /^#?([0-9a-f]{6})$/i.exec(String(hex ?? '').trim());
+  if (!m) return null;
+  const [r, g, b] = [0, 2, 4].map((i) => {
+    const c = parseInt(m[1].slice(i, i + 2), 16) / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** The initial on a rounded tile of the brand colour, as SVG. */
+export function monogramSvg({ letter, background, ink = '#1e2433' }) {
+  const bg = luminance(background) === null ? '#1e2433' : background;
+  const fg = (luminance(bg) ?? 0) > 0.5 ? ink : '#ffffff';
+  return (
+    '<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 64 64">' +
+    `<rect width="64" height="64" rx="14" fill="${bg}"/>` +
+    (letter
+      ? `<text x="32" y="44.5" text-anchor="middle" font-family="Poppins, Inter, Helvetica, Arial, sans-serif" font-weight="700" font-size="36" fill="${fg}">${letter}</text>`
+      : '') +
+    '</svg>'
+  );
+}
+
+/** An .ico file holding each image as a PNG (Windows Vista+ and every current browser). */
+export function icoFromPngs(images) {
+  const header = Buffer.alloc(6);
+  header.writeUInt16LE(0, 0); // reserved
+  header.writeUInt16LE(1, 2); // 1 = icon
+  header.writeUInt16LE(images.length, 4);
+  let offset = 6 + 16 * images.length;
+  const entries = images.map(({ size, png }) => {
+    const e = Buffer.alloc(16);
+    e.writeUInt8(size >= 256 ? 0 : size, 0); // width (0 means 256)
+    e.writeUInt8(size >= 256 ? 0 : size, 1); // height
+    e.writeUInt16LE(1, 4); // colour planes
+    e.writeUInt16LE(32, 6); // bits per pixel
+    e.writeUInt32LE(png.length, 8);
+    e.writeUInt32LE(offset, 12);
+    offset += png.length;
+    return e;
+  });
+  return Buffer.concat([header, ...entries, ...images.map((i) => i.png)]);
+}
+
+const readJson = (url) => {
+  try {
+    return JSON.parse(readFileSync(url, 'utf8'));
+  } catch {
+    return {};
+  }
+};
+
+/** A site path such as `/uploads/crest.png` → its file in public/, if it's there. */
+function publicFile(root, path) {
+  if (typeof path !== 'string' || !path.startsWith('/') || path.includes('..')) return null;
+  const file = new URL(`public${path}`, root);
+  return existsSync(file) ? file : null;
+}
+
+/**
+ * Write `favicon.ico` and `apple-touch-icon.png` into the build output. Never throws.
+ * @param {{ root: URL, outDir: URL, sharp: any, warn?: (message: string) => void }} p
+ * @returns {Promise<{ source: 'favicon' | 'logo' | 'initial' | null, wrote: string[] }>}
+ */
+export async function writeSiteIcons({ root, outDir, sharp, warn = (m) => console.warn(m) }) {
+  const wanted = ['favicon.ico', 'apple-touch-icon.png'].filter((name) => !existsSync(new URL(`public/${name}`, root)));
+  if (!wanted.length) return { source: null, wrote: [] };
+  if (!sharp) {
+    warn('[ferst] No browser icon written: the image library (sharp) is not installed.');
+    return { source: null, wrote: [] };
+  }
+  try {
+    const logos = readJson(new URL('src/content/logoSettings/index.json', root));
+    const settings = readJson(new URL('src/content/siteSettings/index.json', root));
+    const theme = readJson(new URL('src/content/themeSettings/index.json', root));
+
+    let source = 'initial';
+    let input = null;
+    const chosen = publicFile(root, logos.favicon);
+    if (chosen) {
+      source = 'favicon';
+      input = readFileSync(chosen);
+    } else {
+      const logo = publicFile(root, logos.primaryLogoLight);
+      if (logo) {
+        const { width, height } = await sharp(readFileSync(logo)).metadata();
+        if (width && height && width / height >= SQUARE[0] && width / height <= SQUARE[1]) {
+          source = 'logo';
+          input = readFileSync(logo);
+        }
+      }
+    }
+    if (!input) {
+      const name = settings.identity?.shortName || settings.identity?.siteTitle || '';
+      input = Buffer.from(monogramSvg({ letter: initialOf(name), background: theme.brand, ink: theme.ink }));
+    }
+
+    const draw = (size) =>
+      sharp(input, { density: 384 })
+        .resize(size, size, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+        .png();
+    const wrote = [];
+    if (wanted.includes('favicon.ico')) {
+      const images = await Promise.all([32, 48].map(async (size) => ({ size, png: await draw(size).toBuffer() })));
+      writeFileSync(new URL('favicon.ico', outDir), icoFromPngs(images));
+      wrote.push('favicon.ico');
+    }
+    if (wanted.includes('apple-touch-icon.png')) {
+      const ground = luminance(theme.surface) === null ? '#ffffff' : theme.surface;
+      writeFileSync(new URL('apple-touch-icon.png', outDir), await draw(180).flatten({ background: ground }).toBuffer());
+      wrote.push('apple-touch-icon.png');
+    }
+    return { source, wrote };
+  } catch (e) {
+    warn(`[ferst] No browser icon written: ${e?.message ?? e}`);
+    return { source: null, wrote: [] };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.7.13",
+  "version": "0.8.1",
   "type": "module",
   "description": "Ferst Core — the shared, brand-agnostic client-site system: Astro components, layouts, content schemas, the layered config resolver, and a neutral styling architecture that every client overrides.",
   "license": "BUSL-1.1",

package/routes/404.astro

@@ -0,0 +1,36 @@
+---
+/**
+ * The "page not found" page (`/404` → `404.html`): INJECTED by the ferst() integration.
+ * Cloudflare Pages answers a missing address with this page and a real 404 status. Without
+ * a `404.html` it serves the HOME PAGE with a 200 instead (a "soft 404"): search engines
+ * would see the home page at every mistyped or retired address, and a broken link would
+ * look fine to visitors and to the migration's redirect check. A site with its own
+ * `src/pages/404.astro` keeps it (the integration skips this route then).
+ */
+import Base from '../layouts/Base.astro';
+import BlockRenderer from '../components/BlockRenderer.astro';
+import { pageSchema } from '../content/blocks';
+
+const blog = import.meta.env.FERST_ROUTES_BLOG !== false;
+const page = pageSchema.parse({
+  title: 'Page not found',
+  blocks: [
+    {
+      type: 'hero',
+      title: 'Page not found',
+      subtitle: "The page you were looking for isn't here. It may have moved, or the link may be out of date.",
+    },
+    {
+      type: 'prose',
+      variant: 'lead',
+      text: blog ? 'The home page, or the latest news, is a good place to start.' : 'The home page is a good place to start.',
+    },
+    { type: 'button', label: 'Go to the home page', href: '/' },
+    ...(blog ? [{ type: 'button', label: 'Latest news', href: '/posts/', variant: 'secondary' }] : []),
+  ],
+});
+---
+
+<Base title={page.title} description="This page isn't here." indexable={false}>
+  <BlockRenderer blocks={page.blocks} />
+</Base>

package/routes/cookie-policy.astro

@@ -1,25 +1,26 @@
 ---
 /**
  * The cookie policy (`/cookie-policy`) — INJECTED by the ferst() integration, so the
- * cookie banner's link always resolves. Generated from what this site actually uses:
- * every block type on its pages (third-party embeds such as maps or video) and whether a
- * calendar is configured. A site with its own `src/pages/cookie-policy.astro` keeps it
+ * cookie banner's link always resolves. Generated from what this site actually loads:
+ * the blocks on its pages and their sources (a YouTube video is listed; a video file the
+ * site hosts is not; a map with no address loads nothing) and whether a calendar is
+ * configured. A site with its own `src/pages/cookie-policy.astro` keeps it
  * (the integration skips this route then).
  */
 import Base from '../layouts/Base.astro';
 import CookiePolicy from '../components/CookiePolicy.astro';
 import { getPageEntries } from '../lib/pages';
 import { getCalendarSettings } from '../lib/calendar';
-import { blockTypesIn, scanCookieUses } from '../content/cookies';
+import { scanCookieUses, type BlockLike } from '../content/cookies';
 import { pageSchema } from '../content/blocks';
 
-const blockTypes = new Set<string>();
+const blocks: BlockLike[] = [];
 for (const entry of await getPageEntries()) {
   const page = pageSchema.safeParse(entry.data);
-  if (page.success) blockTypesIn(page.data.blocks as Array<{ type: string; blocks?: unknown }>, blockTypes);
+  if (page.success) blocks.push(...(page.data.blocks as BlockLike[]));
 }
 const cal = await getCalendarSettings();
-const model = scanCookieUses({ blockTypes, calendarConfigured: Boolean(cal.embedUrl) });
+const model = scanCookieUses({ blocks, calendarConfigured: Boolean(cal.embedUrl) });
 ---
 
 <Base title="Cookie Policy" description="What this site stores on your device, and the third-party content it can show.">

package/routes/robots.txt.ts

@@ -0,0 +1,15 @@
+// /robots.txt: injected by the ferst() integration (lib/seo.mjs explains the rules). The
+// live site names its sitemap; a test copy stays crawlable so engines see its noindex.
+import type { APIRoute } from 'astro';
+import { robotsTxt } from '../lib/seo.mjs';
+
+export const prerender = true;
+
+export const GET: APIRoute = () =>
+  new Response(
+    robotsTxt({
+      siteUrl: import.meta.env.FERST_SITE_URL || null,
+      production: import.meta.env.FERST_SEO_PRODUCTION !== false,
+    }),
+    { headers: { 'Content-Type': 'text/plain; charset=utf-8' } },
+  );

package/routes/sitemap.xml.ts

@@ -0,0 +1,37 @@
+// /sitemap.xml: injected by the ferst() integration once the site has an address
+// (`ferst-site.json` `siteUrl`). It lists every published page, the posts index, each post
+// and each tag page in use, and the calendar when it's set up. Drafts, hidden tags, later
+// listing pages (/posts/page/2…) and the cookie policy stay out.
+import type { APIRoute } from 'astro';
+import { getPageEntries, pageRouteParams } from '../lib/pages';
+import { canonicalUrl, sitemapXml } from '../lib/seo.mjs';
+
+export const prerender = true;
+
+export const GET: APIRoute = async () => {
+  const site = String(import.meta.env.FERST_SITE_URL || '');
+  const entries: Array<{ loc: string; lastmod?: Date }> = [];
+
+  for (const page of await getPageEntries()) {
+    const { slug } = pageRouteParams(page.id);
+    entries.push({ loc: canonicalUrl(site, slug ? `/${slug}` : '/') });
+  }
+
+  if (import.meta.env.FERST_ROUTES_BLOG !== false) {
+    const { getPublishedPosts, getUsedTags } = await import('../lib/posts');
+    const posts = await getPublishedPosts();
+    if (posts.length) entries.push({ loc: canonicalUrl(site, '/posts'), lastmod: posts[0].data.date });
+    for (const post of posts) entries.push({ loc: canonicalUrl(site, `/posts/${post.slug}`), lastmod: post.data.date });
+    for (const tag of await getUsedTags()) {
+      if (!tag.hidden && tag.count > 0) entries.push({ loc: canonicalUrl(site, `/posts/tag/${tag.slug}`) });
+    }
+  }
+
+  if (import.meta.env.FERST_ROUTES_CALENDAR !== false) {
+    const { getCalendarSettings } = await import('../lib/calendar');
+    const calendar = await getCalendarSettings();
+    if (calendar?.embedUrl) entries.push({ loc: canonicalUrl(site, '/calendar') });
+  }
+
+  return new Response(sitemapXml(entries), { headers: { 'Content-Type': 'application/xml; charset=utf-8' } });
+};