create-website-build-kit 0.1.16 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Scaffold a production marketing site \u2014 Astro on Cloudflare Workers, with the gates, the migration playbook and the accessibility work already wired.",
   "keywords": [
     "astro",

package/template/CLAUDE.md

@@ -111,6 +111,11 @@ weakened scrim.** On a real site two of three regions could not fail at any phot
 exposure was a scrim lightened from 92% to 62% so a client's photography could show its colour.
 This check is what makes weakening one safe.
 
+**Navigation may be CMS-managed; redirects may not.** `check:cms` resolves every internal path in
+CMS-managed data against `src/pages`, so a menu item pointing at a missing page fails the build
+rather than 404ing for a visitor. A redirect has no such check — a client toggling one off is
+silent traffic loss — so it stays in code.
+
 ⚠ **A CMS DELETES EVERY KEY ITS SCHEMA FORGOT.** It rewrites the whole file from the schema, so
 anything undeclared is absent from what it writes back — the client changes one field, saves, and
 the rest is gone, looking like an ordinary content commit. `npm run check:cms` refuses a

package/template/scripts/check-cms.mjs

@@ -42,6 +42,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { parse } from 'yaml';
 import { literalImages } from './lib/literal-images.mjs';
+import { routeExists, routesFromPages } from './lib/routes.mjs';
 
 const RESET = '\x1b[0m';
 const RED = '\x1b[31m';
@@ -322,6 +323,83 @@ for (const entry of entries) {
   }
 }
 
+/* ── internal links a client can type ────────────────────────────────────── */
+
+/*
+ * ⚠ THIS IS WHAT MAKES NAVIGATION SAFE TO PUT IN A CMS.
+ *
+ *   `stacks.md` kept nav out of the CMS for a good reason — a bad value should
+ *   fail the build, not publish. A typo'd path gives a menu item leading to a
+ *   404: the page renders, nothing errors, and only a visitor finds it.
+ *
+ *   But navigation was missing from all five audited sites, so every client had
+ *   to ask for a menu change. That is not a rule being respected, it is a gap
+ *   the rule creates. The answer is not to forbid the field, it is to verify
+ *   it — before the build, while somebody is still looking at the config.
+ *
+ * ⚠ A DYNAMIC ROUTE IS A PATTERN. `[slug].astro` serves every legal page, so
+ *   treating routes as literal strings would report most of a site as broken.
+ *   `routesFromPages` returns patterns for those and `routeExists` matches them.
+ *
+ * External links, `mailto:`, `tel:` and bare anchors are somebody else's
+ * problem — `verify` checks those against the deployed site, where they can
+ * actually be resolved.
+ */
+const LINKISH = /(^|\.)(href|url|link|to|target|destination)$/i;
+const routes = routesFromPages();
+const brokenLinks = [];
+
+if (routes.static.size || routes.dynamic.length) {
+  for (const entry of entries) {
+    const documents = [];
+    if (entry?.type === 'collection' && existsSync(entry.path ?? '')) {
+      const walk = (d) =>
+        readdirSync(d).flatMap((e) => {
+          const full = join(d, e);
+          return statSync(full).isDirectory() ? walk(full) : [full];
+        });
+      for (const file of walk(entry.path).filter((f) => /\.mdx?$/.test(f))) {
+        const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(file, 'utf8'));
+        if (!m) continue;
+        try {
+          documents.push({ where: rel(file), data: parse(m[1]) ?? {} });
+        } catch {
+          /* reported elsewhere */
+        }
+      }
+    } else if (/\.json$/.test(entry?.path ?? '') && existsSync(entry.path)) {
+      try {
+        documents.push({ where: rel(entry.path), data: JSON.parse(readFileSync(entry.path, 'utf8')) });
+      } catch {
+        /* reported above */
+      }
+    }
+
+    for (const doc of documents) {
+      const visit = (value, path) => {
+        if (Array.isArray(value)) return value.forEach((v) => visit(v, path));
+        if (value && typeof value === 'object') {
+          for (const [k, v] of Object.entries(value)) visit(v, path ? `${path}.${k}` : k);
+          return;
+        }
+        if (typeof value !== 'string' || !LINKISH.test(path)) return;
+        if (!value.startsWith('/')) return; // external, mailto:, tel:, #anchor
+        if (routeExists(value, routes)) return;
+        brokenLinks.push({ where: doc.where, path, value });
+      };
+      visit(doc.data, '');
+    }
+  }
+}
+
+if (brokenLinks.length) {
+  problems.push({
+    label: 'internal links',
+    why: `${brokenLinks.length} point at a page this site does not serve`,
+    links: brokenLinks,
+  });
+}
+
 /* ── coverage, and secrets ───────────────────────────────────────────────── */
 
 /*
@@ -483,6 +561,16 @@ for (const p of problems) {
         `      the client will never touch — or move them out of a CMS-managed file.${RESET}`,
     );
   }
+  if (p.links) {
+    for (const l of p.links.slice(0, 8)) {
+      console.error(`      ${DIM}${l.where}  ${l.path} = ${JSON.stringify(l.value)}${RESET}`);
+    }
+    console.error(
+      `      ${DIM}A menu item pointing at a missing page renders perfectly and 404s only\n` +
+        `      for a visitor. This is what lets navigation be a CMS field at all: the\n` +
+        `      value is checked before the build rather than trusted.${RESET}`,
+    );
+  }
   if (p.picker) {
     console.error(
       `      ${DIM}The site still renders this: <Img> accepts a manifest key as well as a\n` +

package/template/scripts/lib/routes.mjs

@@ -96,3 +96,70 @@ export async function discoverRoutes(origin, fetcher = fetch) {
 
   return { routes: [], source: 'nothing — no sitemap and no dist/' };
 }
+
+/**
+ * Routes derived from `src/pages`, without building anything.
+ *
+ * ── WHY NOT routesFromDist ─────────────────────────────────────────────────
+ * `check-cms.mjs` runs BEFORE the build, so `dist/` does not exist yet. The
+ * point of checking a navigation target early is to fail while somebody is
+ * still looking at the config, not after a deploy.
+ *
+ * Returns `{ static: Set<string>, dynamic: RegExp[] }`.
+ *
+ * ⚠ A DYNAMIC ROUTE IS A PATTERN, NOT A ROUTE. `[slug].astro` serves every
+ *   legal page and `[...path].astro` serves any depth. Treating those as
+ *   literal strings would report every real link through them as broken, which
+ *   on a site with a `[slug]` catch-all is *most of the site* — a check that
+ *   confident and that wrong gets switched off within a day.
+ *
+ * ⚠ ENDPOINTS ARE NOT PAGES. `robots.txt.ts` and `api/contact.ts` produce
+ *   responses, never navigable pages, so they are excluded — nobody puts them
+ *   in a menu and reporting them as available would be noise.
+ */
+export function routesFromPages(dir = 'src/pages') {
+  const out = { static: new Set(), dynamic: [] };
+  if (!existsSync(dir)) return out;
+
+  const walk = (d) =>
+    readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+      const full = join(d, e.name);
+      return e.isDirectory() ? walk(full) : [full];
+    });
+
+  for (const file of walk(dir)) {
+    const rel = relative(dir, file).split(sep).join('/');
+    /* `_` prefixed files and directories are not routed by Astro. */
+    if (rel.split('/').some((part) => part.startsWith('_'))) continue;
+    if (!/\.(astro|md|mdx)$/.test(rel)) continue; // .ts endpoints are not pages
+
+    const path =
+      '/' +
+      rel
+        .replace(/\.(astro|md|mdx)$/, '')
+        .replace(/(^|\/)index$/, '$1')
+        .replace(/\/$/, '');
+    const route = path === '/' ? '/' : `${path}/`.replace(/\/+/g, '/');
+
+    if (route.includes('[')) {
+      /* [...rest] matches any depth; [slug] matches one segment. */
+      const pattern = route
+        .replace(/[.*+?^${}()|\\]/g, '\\$&')
+        .replace(/\[\.\.\.[^\]]+\]/g, '.+')
+        .replace(/\[[^\]]+\]/g, '[^/]+');
+      out.dynamic.push(new RegExp(`^${pattern}$`));
+    } else {
+      out.static.add(route);
+    }
+  }
+
+  return out;
+}
+
+/** Does `href` correspond to a page this site serves? */
+export function routeExists(href, routes) {
+  const path = href.split('#')[0].split('?')[0];
+  const normalised = path.endsWith('/') || path === '' ? path || '/' : `${path}/`;
+  if (routes.static.has(normalised)) return true;
+  return routes.dynamic.some((re) => re.test(normalised));
+}