ferst-core 0.9.1 → 0.9.3

package/bin/cms-config.mjs

@@ -108,18 +108,47 @@ export function deploymentBranch() {
   return 'main';
 }
 
+/** Ferst's managed GitHub org: its sites are on the Basic plan. */
+const MANAGED_OWNER = 'myai4webdev';
+
+/** The Pages collection's description on each plan. */
+const PAGES_DESCRIPTION = {
+  basic: "See each page and request a change — our team makes it and sends it back for you to check. You don't edit the page layout here.",
+  free: "You're on the free plan: you look after this site yourself and change its pages in your own repository. Asking the Ferst team to make changes for you comes with the Basic plan.",
+};
+
+/**
+ * The site's plan, for what its CMS offers. Requests (the Ferst team making a change for the
+ * site's people) come with the Basic plan: a managed site. A self-managed site, the client's
+ * own repo, is on the free plan and makes its own changes. The plan the platform records in
+ * `ferst-site.json` wins; otherwise the repo's owner decides. Unknown keeps the requests field:
+ * the platform refuses a free-plan site's request anyway.
+ * @param {string} repo owner/name
+ * @param {{ plan?: string }} [site] the parsed ferst-site.json
+ * @returns {'basic' | 'free'}
+ */
+export function planFor(repo, site = {}) {
+  if (site && (site.plan === 'basic' || site.plan === 'free')) return site.plan;
+  const owner = String(repo ?? '').split('/')[0].trim().toLowerCase();
+  if (!owner) return 'basic';
+  return owner === MANAGED_OWNER ? 'basic' : 'free';
+}
+
 /**
- * Fill the config template's placeholders. Pure — unit-testable.
+ * Fill the config template's placeholders. Pure — unit-testable. On the free plan the
+ * `# ferst:requests` … `# /ferst:requests` block (the pages' "Requested changes") is left out.
  * @param {string} tpl the template contents
- * @param {{ repo: string, base: string, branch: string }} vars
+ * @param {{ repo: string, base: string, branch: string, plan?: 'basic' | 'free' }} vars
  * @returns {string}
  */
-export function fillConfig(tpl, { repo, base, branch }) {
-  const out = tpl
+export function fillConfig(tpl, { repo, base, branch, plan = 'basic' }) {
+  const forPlan = plan === 'free' ? tpl.replace(/^[ \t]*# ferst:requests\b[\s\S]*?^[ \t]*# \/ferst:requests[^\n]*\n/m, '') : tpl;
+  const out = forPlan
     .split('__REPO__').join(repo)
     .split('__API_ROOT__').join(`${base}/git`)
     .split('__BASE_URL__').join(base)
-    .split('__BRANCH__').join(branch);
+    .split('__BRANCH__').join(branch)
+    .split('__PAGES_DESCRIPTION__').join(PAGES_DESCRIPTION[plan] ?? PAGES_DESCRIPTION.basic);
   const leftover = out.match(/__[A-Z][A-Z_]*__/);
   if (leftover) {
     throw new Error(`ferst-cms-config: unfilled placeholder ${leftover[0]} — add it to the filler.`);
@@ -147,9 +176,17 @@ function main() {
     process.exit(1);
   }
 
+  let site = {};
+  try {
+    site = JSON.parse(readFileSync(resolve(process.cwd(), 'ferst-site.json'), 'utf8')) ?? {};
+  } catch {
+    /* no ferst-site.json: the repo's owner decides the plan */
+  }
+  const plan = planFor(repo, site);
+
   let out;
   try {
-    out = fillConfig(tpl, { repo, base, branch });
+    out = fillConfig(tpl, { repo, base, branch, plan });
   } catch (e) {
     console.error(String(e.message ?? e));
     process.exit(1);
@@ -157,7 +194,7 @@ function main() {
 
   mkdirSync(dirname(outPath), { recursive: true });
   writeFileSync(outPath, out);
-  console.log(`ferst-cms-config: wrote ${outPath} (repo=${repo}, branch="${branch}", base=${base})`);
+  console.log(`ferst-cms-config: wrote ${outPath} (repo=${repo}, branch="${branch}", base=${base}, plan=${plan})`);
 }
 
 // Run when invoked directly as a bin — including via npm's node_modules/.bin symlink.

package/cms/config.template.yml

@@ -234,7 +234,7 @@ collections:
   - name: pages
     label: Pages
     label_singular: Page
-    description: "See each page and request a change — our team makes it and sends it back for you to check. You don't edit the page layout here."
+    description: "__PAGES_DESCRIPTION__"
     folder: src/content/pages
     extension: json
     format: json
@@ -244,6 +244,7 @@ collections:
     identifier_field: title
     fields:
       - { name: title, label: Page title, widget: string }
+      # ferst:requests (the Basic plan only: bin/cms-config.mjs leaves it out on the free plan)
       - name: requests
         label: Requested changes
         label_singular: Request
@@ -258,6 +259,7 @@ collections:
           - { name: issue, widget: hidden, required: false }
           - { name: by, widget: hidden, required: false }
           - { name: at, widget: hidden, required: false }
+      # /ferst:requests
       - { name: description, label: SEO description, widget: hidden, required: false }
       - { name: heroImage, widget: hidden, required: false }
       - { name: align, widget: hidden, required: false }

package/content/schemas.ts

@@ -36,7 +36,8 @@ const siteIdentitySchema = z
     /** Town / city — appended to the brand in alt text. */
     location: z.string().default(''),
     /** What the site is for, which types its structured data for search engines
-     *  (lib/structured-data.mjs): Church, School, NGO, LocalBusiness or Organization. */
+     *  (lib/structured-data.mjs): School, NGO, LocalBusiness or Organization. A church is an
+     *  Organization (the parish), its churches its places. */
     kind: z.enum(['church', 'school', 'charity', 'business', 'organisation']).default('organisation'),
   })
   .default({});

package/integration.mjs

@@ -35,16 +35,28 @@
  *   `public/` win.
  * @param {boolean} [options.seo=true] Search signals (lib/seo.mjs): `/robots.txt`, and once
  *   `ferst-site.json` has a `siteUrl`, `/sitemap.xml`, a canonical address on every page,
- *   structured data and link previews, and (with the blog) `/posts/rss.xml`.
+ *   structured data and link previews, and (with the blog) `/posts/rss.xml`. Every build's
+ *   internal links to a page point at its own address (`/about-us/`), not at a redirect.
  *   A test copy (any branch but the production one) is marked noindex on every file. A
  *   site's own `public/robots.txt` or `public/sitemap.xml` wins.
  * @returns {import('astro').AstroIntegration}
  */
 import { copyFileSync, createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { deploymentBranch } from './bin/cms-config.mjs';
-import { seoContext, withNoindexHeader } from './lib/seo.mjs';
+import { linksToPageAddresses, seoContext, withNoindexHeader } from './lib/seo.mjs';
 import { writeSiteIcons } from './lib/site-icon.mjs';
 
+/** Every page of a build (its .html files, at any depth), as file URLs. */
+function htmlFiles(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
+    entry.isDirectory()
+      ? htmlFiles(new URL(`${encodeURIComponent(entry.name)}/`, dir))
+      : entry.name.endsWith('.html')
+        ? [new URL(encodeURIComponent(entry.name), dir)]
+        : [],
+  );
+}
+
 /** The self-hosted fonts the engine's CSS requests (/fonts/*.woff2), shipped in the package. */
 const FONTS_DIR = new URL('./fonts/', import.meta.url);
 const FONT_URL = /^\/fonts\/([a-z0-9-]+\.woff2)(?:\?.*)?$/;
@@ -197,6 +209,21 @@ export default function ferst(options = {}) {
       'astro:server:setup': fonts['astro:server:setup'],
       'astro:build:done': async (ctx) => {
         await fonts['astro:build:done'](ctx);
+        // Internal links point at each page's one address, never at a redirect (lib/seo.mjs).
+        if (seo) {
+          const isPage = (path) => {
+            try {
+              return existsSync(new URL(`.${path}index.html`, ctx.dir));
+            } catch {
+              return false;
+            }
+          };
+          for (const file of htmlFiles(ctx.dir)) {
+            const html = readFileSync(file, 'utf8');
+            const linked = linksToPageAddresses(html, isPage);
+            if (linked !== html) writeFileSync(file, linked);
+          }
+        }
         // A test copy is noindex on every file: pages, and the PDFs and images beside them.
         if (search && !search.production) {
           const file = new URL('_headers', ctx.dir);

package/layouts/Base.astro

@@ -32,6 +32,7 @@ import { getCalloutSettings } from '../lib/callout';
 import { buildThemeStyle } from '../lib/themeTokens';
 import { canonicalUrl, previewTags } from '../lib/seo.mjs';
 import { structuredData } from '../lib/structured-data.mjs';
+import { titlesAbove } from '../lib/pages';
 
 interface Props {
   title: string;
@@ -101,9 +102,13 @@ const canonical = siteUrl && indexable ? canonicalUrl(siteUrl, path) : null;
 const noindex = !indexable || import.meta.env.FERST_SEO_PRODUCTION === false;
 
 // What the page tells search engines and link previews about the site (lib/structured-data,
-// lib/seo): from the site's own details, the same facts it shows visitors.
+// lib/seo): from the site's own details, the same facts it shows visitors. A nested page also
+// carries its breadcrumb trail, from the titles of the pages above it.
+const nested = path.split('/').filter(Boolean).length >= 2;
+const breadcrumbs = indexable && siteUrl && nested ? await titlesAbove(path) : {};
 const ld = indexable
   ? structuredData({
+      breadcrumbs,
       siteUrl: siteUrl || null,
       path,
       identity,

package/lib/pages.ts

@@ -22,6 +22,24 @@
  * can still hand-build a one-off page beside the JSON-driven ones.
  */
 import { getCollection } from 'astro:content';
+import { getPostsSettings } from './posts';
+
+/**
+ * The titles of the pages above a nested address, for its breadcrumb trail
+ * (lib/structured-data): each address above it that is a page of its own, and the news page
+ * above a post. Keyed by address (`/about-us/`).
+ */
+export async function titlesAbove(path: string): Promise<Record<string, string>> {
+  const segments = path.split('/').filter(Boolean);
+  const above = new Set(segments.slice(0, -1).map((_, i) => segments.slice(0, i + 1).join('/')));
+  const titles: Record<string, string> = {};
+  if (!above.size) return titles;
+  for (const entry of await getPageEntries()) {
+    if (above.has(entry.id) && entry.data.title) titles[`/${entry.id}/`] = entry.data.title;
+  }
+  if (above.has('posts') && !titles['/posts/']) titles['/posts/'] = (await getPostsSettings()).title;
+  return titles;
+}
 
 /** All non-draft `pages` entries. */
 export async function getPageEntries() {

package/lib/seo.mjs

@@ -129,6 +129,22 @@ export function withNoindexHeader(existing) {
   return `${current.replace(/\s*$/, '')}\n\n${NOINDEX_RULE}`;
 }
 
+/**
+ * Internal links pointed at each page's one address. A page's address is its trailing-slash
+ * form (`/about-us/`), and Cloudflare Pages answers the slash-less form with a redirect: a link
+ * to `/about-us` costs every visit and crawl a hop, and search engines list the slash-less form
+ * as a page with a redirect. So `href="/about-us"` gains its slash, keeping any `?query` or
+ * `#section`, when `isPage('/about-us/')` says that page exists. Files, other sites and
+ * addresses that are already right are left alone.
+ * @param {string} html
+ * @param {(path: string) => boolean} isPage  whether `/x/` is a page of the site
+ */
+export function linksToPageAddresses(html, isPage) {
+  return String(html).replace(/(\shref=")(\/(?!\/)[^"?#]*[^"/?#])([?#][^"]*)?"/g, (match, attr, path, rest = '') =>
+    isPage(`${path}/`) ? `${attr}${path}/${rest}"` : match,
+  );
+}
+
 /**
  * Link-preview tags (Open Graph and Twitter card) for one page: what a link shared on
  * Facebook, WhatsApp or LinkedIn shows. The picture is the page's own (its hero), else the

package/lib/structured-data.mjs

@@ -4,17 +4,18 @@
  * same facts the site shows visitors. Base renders it in each page's head once the site has
  * an address (its links must be absolute). Pure, so it's unit-testable.
  *
- * - The site is one entity (`#organization`), typed by its kind: a church with one place is
- *   a `Church` at that address; with several places (a parish of several churches) it's an
- *   `Organization` with each church as a `location`.
+ * - The site is one entity (`#organization`), typed by its kind. A church site is the parish,
+ *   an `Organization` with each of its churches as a `location` (schema.org's `Church` is a
+ *   building, and a building can't publish the website or write its posts); with one church,
+ *   the parish is at that church's address. Other kinds list several places as `location`s.
  * - The website names that entity as its publisher.
  * - A post is an `Article`, dated, published by the site.
  */
 import { canonicalUrl } from './seo.mjs';
 
-/** The schema.org type for each kind of site (`identity.kind`). */
-const TYPE = { church: 'Church', school: 'School', charity: 'NGO', business: 'LocalBusiness', organisation: 'Organization' };
-/** The type of each of a site's places, when it has several. */
+/** The schema.org type for each kind of site (`identity.kind`). A church site is an `Organization`. */
+const TYPE = { school: 'School', charity: 'NGO', business: 'LocalBusiness', organisation: 'Organization' };
+/** The type of each of a site's places, when it lists them. */
 const PLACE_TYPE = { church: 'Church', school: 'School', business: 'LocalBusiness' };
 
 /** Drop empty values (undefined, '', empty arrays and objects) so the data says only what's known. */
@@ -36,22 +37,45 @@ const isoDate = (d) => {
   return Number.isNaN(date.getTime()) ? undefined : date.toISOString().slice(0, 10);
 };
 
+/**
+ * The trail to a nested page (the site › each page above it › the page), or undefined for a
+ * top-level page. `titles` maps each address above the page to its page title; an address
+ * that isn't a page of its own is left out, and a trail with nothing between the site and
+ * the page isn't worth showing.
+ */
+function breadcrumbList(site, path, title, siteName, titles) {
+  const segments = String(path).split('/').filter(Boolean);
+  if (segments.length < 2 || !title) return undefined;
+  const items = [{ name: siteName, item: `${site}/` }];
+  for (let i = 1; i < segments.length; i++) {
+    const above = `/${segments.slice(0, i).join('/')}/`;
+    if (titles[above]) items.push({ name: titles[above], item: canonicalUrl(site, above) });
+  }
+  if (items.length < 2) return undefined;
+  items.push({ name: title, item: canonicalUrl(site, path) });
+  return {
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((it, i) => ({ '@type': 'ListItem', position: i + 1, name: it.name, item: it.item })),
+  };
+}
+
 /**
  * The JSON-LD for one page, or null when the site has no address.
  * @param {{ siteUrl: string | null, path: string, identity: any, contact: any, places?: any[], logo?: string,
- *   title?: string, description?: string, article?: { date: Date | string, image?: string } }} p
+ *   title?: string, description?: string, article?: { date: Date | string, image?: string },
+ *   breadcrumbs?: Record<string, string> }} p  `breadcrumbs`: the titles of the pages above this one.
  */
-export function structuredData({ siteUrl, path, identity, contact = {}, places = [], logo, title, description, article }) {
+export function structuredData({ siteUrl, path, identity, contact = {}, places = [], logo, title, description, article, breadcrumbs = {} }) {
   if (!siteUrl) return null;
   const site = siteUrl.replace(/\/+$/, '');
   const abs = (u) => (!u ? undefined : /^https?:\/\//i.test(u) ? u : `${site}${u.startsWith('/') ? '' : '/'}${u}`);
   const orgId = `${site}/#organization`;
   const kind = identity?.kind || 'organisation';
   const filled = places.filter((p) => p && (p.name || p.streetAddress || p.postalCode));
-  const several = filled.length > 1;
+  const listPlaces = filled.length > 1 || kind === 'church';
 
   const organisation = clean({
-    '@type': several && kind === 'church' ? 'Organization' : TYPE[kind] || 'Organization',
+    '@type': TYPE[kind] || 'Organization',
     '@id': orgId,
     name: identity?.siteTitle,
     alternateName: identity?.shortName && identity.shortName !== identity.siteTitle ? identity.shortName : undefined,
@@ -62,7 +86,7 @@ export function structuredData({ siteUrl, path, identity, contact = {}, places =
     email: contact.email,
     sameAs: [contact.facebookUrl],
     address: filled.length === 1 ? postal(filled[0]) : undefined,
-    location: several
+    location: listPlaces
       ? filled.map((p) => ({ '@type': PLACE_TYPE[kind] || 'Place', name: p.name, address: postal(p), hasMap: p.mapUrl }))
       : undefined,
   });
@@ -70,6 +94,8 @@ export function structuredData({ siteUrl, path, identity, contact = {}, places =
     organisation,
     { '@type': 'WebSite', '@id': `${site}/#website`, url: `${site}/`, name: identity?.siteTitle, inLanguage: 'en-GB', publisher: { '@id': orgId } },
   ];
+  const trail = breadcrumbList(site, path, title, identity?.siteTitle, breadcrumbs);
+  if (trail) graph.push(trail);
   if (article) {
     graph.push(
       clean({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "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",