create-website-build-kit 0.1.16 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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/package.json

@@ -20,6 +20,7 @@
     "check:copy": "node scripts/check-copy.mjs",
     "check:drift": "node scripts/check-drift.mjs",
     "check:form": "node scripts/check-form.mjs",
+    "check:redirects": "node scripts/check-redirects.mjs",
     "check:secrets": "node scripts/check-secrets.mjs",
     "check:sitemap": "node scripts/check-sitemap.mjs",
     "console": "node scripts/check-console.mjs",

package/template/scripts/build.mjs

@@ -122,10 +122,22 @@ step(process.execPath, ['scripts/check-env.mjs']);
 
 if (env === 'production') {
   step(process.execPath, ['scripts/check-sitemap.mjs']);
+  /* A redirect map is the one migration artefact edited by hand, in bulk, about
+     URLs nobody can see any more. Every failure it has is invisible at deploy. */
+  step(process.execPath, ['scripts/check-redirects.mjs']);
   /* Production only: it measures the GENERATED images, and a staging build is
      often run before `npm run media` has caught up. A no-op until a project
      declares regions — the template has no design and therefore none. */
   step(process.execPath, ['scripts/check-contrast.mjs']);
+
+  /*
+   * Advisory: it exits 0 whatever it finds, because drift is a decision and not
+   * an error. It runs here because a site is current on the day it is scaffolded
+   * and behind some months later — and the build is the only moment anybody is
+   * reliably looking. A check nobody remembers to run is the failure it exists
+   * to catch, applied to itself.
+   */
+  step(process.execPath, ['scripts/check-drift.mjs']);
 }
 
 /* A sanity line, so the log says which environment actually ran rather than

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/check-redirects.mjs

@@ -0,0 +1,187 @@
+/**
+ * Refuse a redirect map that is silently wrong.
+ *
+ *   npm run check:redirects
+ *
+ * Runs in `build:production`. A no-op when there is no `public/_redirects`.
+ *
+ * ── WHY THIS IS ITS OWN CHECK ──────────────────────────────────────────────
+ * `redirects.mjs` PROPOSES a map from the old site's inventory. Nothing has
+ * ever checked the map that a human then edited — and the editing is where the
+ * mistakes are, because a redirect file is the one artefact in a migration
+ * that is written by hand, in bulk, under time pressure, about URLs nobody can
+ * see any more.
+ *
+ * ⚠ EVERY FAILURE BELOW IS INVISIBLE AT DEPLOY. The file parses, the site
+ *   builds, the pages are fine. What breaks is a URL that used to rank, weeks
+ *   later, in somebody else's analytics.
+ *
+ * ── WHAT IT CATCHES, AND WHY EACH ONE MATTERS ──────────────────────────────
+ * **A duplicate source.** Cloudflare takes the FIRST match and ignores the
+ * rest, silently. So the second rule — usually the one somebody added later,
+ * on purpose, to fix something — never fires at all, and the fix appears not
+ * to work for reasons nothing explains.
+ *
+ * **A self-redirect.** `/a → /a` is a loop the browser stops after ~20 hops
+ * with ERR_TOO_MANY_REDIRECTS. The page is simply gone, and it is gone only in
+ * production, because nobody clicks the old URL in development.
+ *
+ * **A loop.** `/a → /b → /a`. The same, with an extra step to hide it.
+ *
+ * **A chain.** `/a → /b → /c` costs a redundant round trip on every visit and
+ * leaks a little PageRank at each hop. Cloudflare resolves only one hop per
+ * request, so a chain is also slower than it looks.
+ *
+ * **An unsupported status.** Cloudflare `_redirects` accepts only
+ * 200/301/302/303/307/308. Anything else makes the platform reject the rule —
+ * see `traps.md`, where a trailing comment rejected the whole FILE.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+
+const FILE = 'public/_redirects';
+const ALLOWED = new Set([200, 301, 302, 303, 307, 308]);
+
+if (!existsSync(FILE)) {
+  console.log(`${DIM}·${RESET} no ${FILE} — nothing to validate`);
+  process.exit(0);
+}
+
+const problems = [];
+const warnings = [];
+const rules = [];
+
+const lines = readFileSync(FILE, 'utf8').split('\n');
+
+lines.forEach((raw, index) => {
+  const line = raw.trim();
+  if (!line || line.startsWith('#')) return;
+
+  /* ⚠ SPLIT ON WHITESPACE, NOT ON A SINGLE SPACE. Columns in a hand-edited
+     file are aligned with runs of spaces, and a naive split reports every
+     aligned rule as malformed — which on a real migration is all of them. */
+  const parts = line.split(/\s+/);
+  const [from, to, status] = parts;
+
+  if (!from || !to) {
+    problems.push({ line: index + 1, why: `is not a rule: ${JSON.stringify(line)}`, raw: line });
+    return;
+  }
+
+  const code = status === undefined ? 301 : Number(status);
+  if (!Number.isInteger(code) || !ALLOWED.has(code)) {
+    problems.push({
+      line: index + 1,
+      why: `status ${JSON.stringify(status)} is not one Cloudflare accepts (200, 301, 302, 303, 307, 308)`,
+      raw: line,
+    });
+    return;
+  }
+
+  rules.push({ line: index + 1, from, to, code, raw: line });
+});
+
+/* ── a duplicate source ───────────────────────────────────────────────────── */
+
+const bySource = new Map();
+for (const rule of rules) {
+  const key = rule.from;
+  if (bySource.has(key)) {
+    problems.push({
+      line: rule.line,
+      why: `duplicate source ${key} — first declared on line ${bySource.get(key).line}. Cloudflare takes the FIRST match, so this rule never fires`,
+      raw: rule.raw,
+    });
+  } else {
+    bySource.set(key, rule);
+  }
+}
+
+/* ── self-redirects, loops and chains ─────────────────────────────────────── */
+
+/* Compare with and without a trailing slash: `/a` and `/a/` are the same page
+   to a reader and to Cloudflare's matcher, and a loop written across the two
+   forms is the one nobody spots by eye. */
+const norm = (p) => (p.length > 1 ? p.replace(/\/+$/, '') : p);
+
+for (const rule of rules) {
+  if (norm(rule.from) === norm(rule.to)) {
+    problems.push({
+      line: rule.line,
+      why: `redirects to itself — a browser stops after about twenty hops and the page is simply gone`,
+      raw: rule.raw,
+    });
+  }
+}
+
+const target = new Map(rules.map((r) => [norm(r.from), r]));
+
+/*
+ * ⚠ WALK FIRST, THEN DECIDE. Reporting a hop as a chain the moment it is seen
+ *   means a LOOP is announced as a chain and then as a loop — two messages, the
+ *   first of them wrong, and the wrong one arrives first. Collect the walk, and
+ *   only call it a chain if it actually terminates.
+ */
+for (const rule of rules) {
+  if (norm(rule.from) === norm(rule.to)) continue; // already reported
+
+  const path = [norm(rule.from)];
+  const hops = [];
+  let cursor = target.get(norm(rule.to));
+  let looped = false;
+
+  while (cursor && hops.length < 20) {
+    const here = norm(cursor.from);
+    if (path.includes(here)) {
+      looped = true;
+      path.push(here);
+      break;
+    }
+    path.push(here);
+    hops.push(cursor);
+    cursor = target.get(norm(cursor.to));
+  }
+
+  if (looped) {
+    problems.push({
+      line: rule.line,
+      why: `is part of a redirect LOOP: ${path.join(' → ')}`,
+      raw: rule.raw,
+    });
+  } else if (hops.length) {
+    const last = hops[hops.length - 1];
+    warnings.push(
+      `line ${rule.line}: ${rule.from} reaches ${last.to} in ${hops.length + 1} hops. ` +
+        `Cloudflare resolves one per request, so point this rule straight at ${last.to}`,
+    );
+  }
+}
+
+/* ── report ──────────────────────────────────────────────────────────────── */
+
+const unique = [...new Set(warnings)];
+for (const w of unique) console.log(`  ${YELLOW}!${RESET} ${w}`);
+
+if (!problems.length) {
+  console.log(
+    `${GREEN}✓${RESET} ${rules.length} redirect rule(s): no duplicates, no loops, every status supported`,
+  );
+  process.exit(0);
+}
+
+console.error(`\n${RED}✗ ${problems.length} problem(s) in ${FILE}${RESET}\n`);
+for (const p of problems) {
+  console.error(`    line ${p.line}  ${p.why}`);
+  console.error(`      ${DIM}${p.raw}${RESET}`);
+}
+console.error(
+  `\n  ${DIM}None of these stop the file parsing or the site building. They break a URL\n` +
+    `  that used to rank, weeks later, in somebody else's analytics.${RESET}\n`,
+);
+process.exit(1);

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));
+}