ferst-core 0.7.12 → 0.8.0

package/integration.mjs

@@ -1,123 +1,195 @@
-/**
- * ferst() — the Astro integration that makes a client site's ROUTING package-owned.
- *
- * A thin client adds `integrations: [ferst()]` to astro.config.mjs and carries
- * ZERO page files: the page catch-all (which also owns the home page), the
- * calendar route and the blog routes are injected from ferst-core. A routing fix
- * then ships as a package bump + rebuild — the same channel component fixes travel
- * through — instead of being hand-copied into every client repo.
- *
- * Irreducible caveat (Astro 5): content collections must be defined in the CONSUMER,
- * so the one-line `src/content/config.ts` re-export stays. "Zero page files" is
- * reachable; "zero files" is not. Explicit client `.astro` routes still win over
- * these injected ones, so a one-off hand-built page is always possible.
- *
- * The blog routes (posts index / individual post / tag pages) inject as a set:
- * the listing components (NewsList, PostsFilter) now live in core, so `/posts`,
- * `/posts/[...slug]` and `/posts/tag/[...tag]` all ship from the package. Turn
- * the whole capability off with `blog: false` (then a client wanting posts hand-
- * builds its own routes over `ferst-core/lib/posts`).
- *
- * @param {object} [options]
- * @param {boolean} [options.calendar=true] Inject the `/calendar` route.
- * @param {boolean} [options.blog=true] Inject the blog routes (`/posts`,
- *   `/posts/[...slug]`, `/posts/tag/[...tag]`).
- * @param {boolean} [options.cookiePolicy=true] Inject `/cookie-policy` (the page the cookie
- *   banner links to), generated from the blocks the site uses. Skipped automatically when
- *   the site has its own `src/pages/cookie-policy.astro`.
- * @returns {import('astro').AstroIntegration}
- */
-import { copyFileSync, createReadStream, existsSync, mkdirSync, readdirSync } from 'node:fs';
-
-/** 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)(?:\?.*)?$/;
-
-/**
- * ferstFonts() — serves the engine's self-hosted fonts in `astro dev` and copies them into
- * every build's `/fonts/`. Included in ferst(); usable on its own (the showcase). A file
- * the site already has in its own `public/fonts/` is never overwritten.
- * @returns {import('astro').AstroIntegration}
- */
-export function ferstFonts() {
-  return {
-    name: 'ferst-fonts',
-    hooks: {
-      'astro:server:setup': ({ server }) => {
-        server.middlewares.use((req, res, next) => {
-          const m = req.url && req.url.match(FONT_URL);
-          if (!m) return next();
-          const file = new URL(m[1], FONTS_DIR);
-          if (!existsSync(file)) return next();
-          res.setHeader('Content-Type', 'font/woff2');
-          res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
-          createReadStream(file).pipe(res);
-        });
-      },
-      'astro:build:done': async ({ dir }) => {
-        const out = new URL('fonts/', dir);
-        mkdirSync(out, { recursive: true });
-        for (const name of readdirSync(FONTS_DIR)) {
-          if (!name.endsWith('.woff2')) continue;
-          const dest = new URL(name, out);
-          if (!existsSync(dest)) copyFileSync(new URL(name, FONTS_DIR), dest);
-        }
-      },
-    },
-  };
-}
-
-export default function ferst(options = {}) {
-  const { calendar = true, blog = true, cookiePolicy = true } = options;
-  return {
-    name: 'ferst',
-    hooks: {
-      'astro:config:setup': ({ injectRoute, config }) => {
-        // Pages + home: the reserved `index` entry renders at `/`, every other
-        // `pages` entry at its own slug (see lib/pages.ts `getSiteRoutes`).
-        injectRoute({
-          pattern: '/[...slug]',
-          entrypoint: 'ferst-core/routes/[...slug].astro',
-        });
-        if (calendar) {
-          injectRoute({
-            pattern: '/calendar',
-            entrypoint: 'ferst-core/routes/calendar/index.astro',
-          });
-        }
-        if (blog) {
-          // The posts capability: index, individual post, and tag pages. Reads
-          // the `posts`/`tags`/`postsSettings` collections (content/collections.ts).
-          injectRoute({
-            pattern: '/posts',
-            entrypoint: 'ferst-core/routes/posts/index.astro',
-          });
-          injectRoute({
-            pattern: '/posts/[...slug]',
-            entrypoint: 'ferst-core/routes/posts/[...slug].astro',
-          });
-          injectRoute({
-            pattern: '/posts/tag/[...tag]',
-            entrypoint: 'ferst-core/routes/posts/tag/[...tag].astro',
-          });
-          // Index pages 2+ (page 1 is /posts; tag pages paginate inside their own route).
-          injectRoute({
-            pattern: '/posts/page/[page]',
-            entrypoint: 'ferst-core/routes/posts/page/[page].astro',
-          });
-        }
-        // The cookie banner links here on every page, so it must always resolve. A site's
-        // own hand-built page wins (Astro would otherwise see two routes for one path).
-        const bespoke = config?.root && existsSync(new URL('src/pages/cookie-policy.astro', config.root));
-        if (cookiePolicy && !bespoke) {
-          injectRoute({
-            pattern: '/cookie-policy',
-            entrypoint: 'ferst-core/routes/cookie-policy.astro',
-          });
-        }
-      },
-      // The engine's self-hosted fonts: served in dev, copied into every build.
-      ...ferstFonts().hooks,
-    },
-  };
-}
+/**
+ * ferst() — the Astro integration that makes a client site's ROUTING package-owned.
+ *
+ * A thin client adds `integrations: [ferst()]` to astro.config.mjs and carries
+ * ZERO page files: the page catch-all (which also owns the home page), the
+ * calendar route and the blog routes are injected from ferst-core. A routing fix
+ * then ships as a package bump + rebuild — the same channel component fixes travel
+ * through — instead of being hand-copied into every client repo.
+ *
+ * Irreducible caveat (Astro 5): content collections must be defined in the CONSUMER,
+ * so the one-line `src/content/config.ts` re-export stays. "Zero page files" is
+ * reachable; "zero files" is not. Explicit client `.astro` routes still win over
+ * these injected ones, so a one-off hand-built page is always possible.
+ *
+ * The blog routes (posts index / individual post / tag pages) inject as a set:
+ * the listing components (NewsList, PostsFilter) now live in core, so `/posts`,
+ * `/posts/[...slug]` and `/posts/tag/[...tag]` all ship from the package. Turn
+ * the whole capability off with `blog: false` (then a client wanting posts hand-
+ * builds its own routes over `ferst-core/lib/posts`).
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.calendar=true] Inject the `/calendar` route.
+ * @param {boolean} [options.blog=true] Inject the blog routes (`/posts`,
+ *   `/posts/[...slug]`, `/posts/tag/[...tag]`).
+ * @param {boolean} [options.cookiePolicy=true] Inject `/cookie-policy` (the page the cookie
+ *   banner links to), generated from the blocks the site uses. Skipped automatically when
+ *   the site has its own `src/pages/cookie-policy.astro`.
+ * @param {boolean} [options.notFound=true] Inject the "page not found" page (`/404` →
+ *   `404.html`). Cloudflare Pages answers a missing address with it and a real 404 status;
+ *   without one it serves the home page with a 200 (a "soft 404"). Skipped automatically
+ *   when the site has its own `src/pages/404.astro` or `public/404.html`.
+ * @param {boolean} [options.seo=true] Search signals (lib/seo.mjs): `/robots.txt`, and once
+ *   `ferst-site.json` has a `siteUrl`, `/sitemap.xml` and a canonical address on every page.
+ *   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';
+
+/** 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)(?:\?.*)?$/;
+
+/**
+ * ferstFonts() — serves the engine's self-hosted fonts in `astro dev` and copies them into
+ * every build's `/fonts/`. Included in ferst(); usable on its own (the showcase). A file
+ * the site already has in its own `public/fonts/` is never overwritten.
+ * @returns {import('astro').AstroIntegration}
+ */
+export function ferstFonts() {
+  return {
+    name: 'ferst-fonts',
+    hooks: {
+      'astro:server:setup': ({ server }) => {
+        server.middlewares.use((req, res, next) => {
+          const m = req.url && req.url.match(FONT_URL);
+          if (!m) return next();
+          const file = new URL(m[1], FONTS_DIR);
+          if (!existsSync(file)) return next();
+          res.setHeader('Content-Type', 'font/woff2');
+          res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+          createReadStream(file).pipe(res);
+        });
+      },
+      'astro:build:done': async ({ dir }) => {
+        const out = new URL('fonts/', dir);
+        mkdirSync(out, { recursive: true });
+        for (const name of readdirSync(FONTS_DIR)) {
+          if (!name.endsWith('.woff2')) continue;
+          const dest = new URL(name, out);
+          if (!existsSync(dest)) copyFileSync(new URL(name, FONTS_DIR), dest);
+        }
+      },
+    },
+  };
+}
+
+/** The site's `ferst-site.json`, or null (no file, or not JSON). */
+function readSiteMeta(root) {
+  if (!root) return null;
+  try {
+    return JSON.parse(readFileSync(new URL('ferst-site.json', root), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Does the site ship this file in its own `public/`? (Its own file wins over ours.) */
+const hasPublicFile = (root, name) => Boolean(root) && existsSync(new URL(`public/${name}`, root));
+
+export default function ferst(options = {}) {
+  const { calendar = true, blog = true, cookiePolicy = true, notFound = true, seo = true } = options;
+  const fonts = ferstFonts().hooks;
+  /** This build's search context, decided at setup and used again when the build is done. */
+  let search = null;
+  return {
+    name: 'ferst',
+    hooks: {
+      'astro:config:setup': ({ injectRoute, updateConfig, config }) => {
+        // Pages + home: the reserved `index` entry renders at `/`, every other
+        // `pages` entry at its own slug (see lib/pages.ts `getSiteRoutes`).
+        injectRoute({
+          pattern: '/[...slug]',
+          entrypoint: 'ferst-core/routes/[...slug].astro',
+        });
+        if (calendar) {
+          injectRoute({
+            pattern: '/calendar',
+            entrypoint: 'ferst-core/routes/calendar/index.astro',
+          });
+        }
+        if (blog) {
+          // The posts capability: index, individual post, and tag pages. Reads
+          // the `posts`/`tags`/`postsSettings` collections (content/collections.ts).
+          injectRoute({
+            pattern: '/posts',
+            entrypoint: 'ferst-core/routes/posts/index.astro',
+          });
+          injectRoute({
+            pattern: '/posts/[...slug]',
+            entrypoint: 'ferst-core/routes/posts/[...slug].astro',
+          });
+          injectRoute({
+            pattern: '/posts/tag/[...tag]',
+            entrypoint: 'ferst-core/routes/posts/tag/[...tag].astro',
+          });
+          // Index pages 2+ (page 1 is /posts; tag pages paginate inside their own route).
+          injectRoute({
+            pattern: '/posts/page/[page]',
+            entrypoint: 'ferst-core/routes/posts/page/[page].astro',
+          });
+        }
+        // The cookie banner links here on every page, so it must always resolve. A site's
+        // own hand-built page wins (Astro would otherwise see two routes for one path).
+        const bespoke = config?.root && existsSync(new URL('src/pages/cookie-policy.astro', config.root));
+        if (cookiePolicy && !bespoke) {
+          injectRoute({
+            pattern: '/cookie-policy',
+            entrypoint: 'ferst-core/routes/cookie-policy.astro',
+          });
+        }
+        // A missing address must answer 404, not the home page (Cloudflare Pages serves the
+        // home page with a 200 when a build has no 404.html). The site's own page wins.
+        const ownNotFound = config?.root && existsSync(new URL('src/pages/404.astro', config.root));
+        if (notFound && !ownNotFound && !hasPublicFile(config?.root, '404.html')) {
+          injectRoute({ pattern: '/404', entrypoint: 'ferst-core/routes/404.astro' });
+        }
+        // Which optional routes this site has, for the pages that link to them (the sitemap,
+        // the "page not found" page).
+        updateConfig?.({
+          vite: {
+            define: {
+              'import.meta.env.FERST_ROUTES_BLOG': JSON.stringify(blog),
+              'import.meta.env.FERST_ROUTES_CALENDAR': JSON.stringify(calendar),
+            },
+          },
+        });
+        // Search signals: the site's address and whether this deploy is the live site (the
+        // production branch) or a test copy, the same rule the CMS uses for its git-proxy.
+        if (seo) {
+          const root = config?.root;
+          search = seoContext({ siteMeta: readSiteMeta(root), branch: deploymentBranch(), env: process.env });
+          updateConfig?.({
+            ...(search.siteUrl && !config?.site ? { site: search.siteUrl } : {}),
+            vite: {
+              define: {
+                'import.meta.env.FERST_SITE_URL': JSON.stringify(search.siteUrl ?? ''),
+                'import.meta.env.FERST_SEO_PRODUCTION': JSON.stringify(search.production),
+              },
+            },
+          });
+          if (!hasPublicFile(root, 'robots.txt')) {
+            injectRoute({ pattern: '/robots.txt', entrypoint: 'ferst-core/routes/robots.txt.ts' });
+          }
+          // A sitemap lists absolute addresses, so it needs the site's address.
+          if (search.siteUrl && !hasPublicFile(root, 'sitemap.xml')) {
+            injectRoute({ pattern: '/sitemap.xml', entrypoint: 'ferst-core/routes/sitemap.xml.ts' });
+          }
+        }
+      },
+      // The engine's self-hosted fonts: served in dev, copied into every build.
+      'astro:server:setup': fonts['astro:server:setup'],
+      'astro:build:done': async (ctx) => {
+        await fonts['astro:build:done'](ctx);
+        // 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);
+          writeFileSync(file, withNoindexHeader(existsSync(file) ? readFileSync(file, 'utf8') : ''));
+        }
+      },
+    },
+  };
+}