create-website-build-kit 0.1.0

package/template/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "site-name",
+  "version": "1.0.0",
+  "private": true,
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "check": "astro check",
+    "a11y": "pa11y-ci --config .pa11yci.json",
+    "a11y:evidence": "node scripts/a11y-evidence.mjs",
+    "reflow": "node scripts/check-reflow.mjs",
+    "console": "node scripts/check-console.mjs",
+    "shots": "node scripts/shots.mjs",
+    "tells": "node scripts/tells.mjs",
+    "media": "node scripts/optimize-media.mjs",
+    "cards": "node scripts/og-cards.mjs",
+    "lastmod": "node scripts/lastmod.mjs",
+    "indexnow": "node scripts/indexnow.mjs",
+    "verify": "node scripts/verify.mjs",
+    "check:sitemap": "node scripts/check-sitemap.mjs",
+    "recon": "node scripts/recon.mjs",
+    "extract": "node scripts/extract.mjs",
+    "dns": "node scripts/dns-snapshot.mjs",
+    "seo": "npx --yes github:nurkamol/seo-audit",
+    "redirects": "node scripts/redirects.mjs",
+    "handover": "node scripts/md-to-pdf.mjs docs/handover.md docs/handover.pdf",
+    "build": "astro build",
+    "build:staging": "PUBLIC_SITE_ENV=staging PUBLIC_SITE_URL=https://new.example.com astro build && PUBLIC_SITE_ENV=staging node scripts/staging-headers.mjs && PUBLIC_SITE_ENV=staging node scripts/check-env.mjs",
+    "build:production": "node scripts/tells.mjs --undecided-only && PUBLIC_SITE_ENV=production astro check && PUBLIC_SITE_ENV=production PUBLIC_SITE_URL=https://example.com astro build && PUBLIC_SITE_ENV=production node scripts/check-env.mjs && node scripts/check-sitemap.mjs",
+    "preview": "wrangler dev",
+    "deploy:staging": "npm run build:staging && wrangler deploy",
+    "deploy:production": "npm run build:production && wrangler deploy"
+  },
+  "dependencies": {
+    "@astrojs/cloudflare": "^14.1.7",
+    "@astrojs/rss": "^4.0.19",
+    "@astrojs/sitemap": "^3.7.3",
+    "astro": "^7.1.6"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@cloudflare/workers-types": "^5.20260815.1",
+    "pa11y-ci": "^4.1.1",
+    "sharp": "^0.35.3",
+    "turndown": "^7.2.4",
+    "typescript": "^6.0.3",
+    "wrangler": "^4.118.0"
+  }
+}

package/template/public/_headers

@@ -0,0 +1,61 @@
+# ── Cache headers for assets the build does not fingerprint ──────────────────
+#
+# The Cloudflare adapter writes an immutable rule for /_astro/* — everything it
+# hashes into a filename. Anything in public/ keeps the name it was given, so it
+# gets the default instead: `public, max-age=0, must-revalidate`. Measured on
+# staging, both webfonts came back with exactly that, which means every visit
+# pays a revalidation round trip for a file that had not changed since the last
+# deploy.
+#
+# ⚠ THESE FILENAMES ARE NOW A CONTRACT. `immutable` tells a browser never to
+# ask again for a year, so a font or a badge REPLACED UNDER THE SAME NAME will
+# not reach anyone who already has it. Change the filename when you change the
+# file. That is the trade for not revalidating.
+
+/fonts/*
+  Cache-Control: public, max-age=31536000, immutable
+
+# Brand artwork: logos, the favicons' PNG fallbacks, the app-store badges.
+/img/brand/*
+  Cache-Control: public, max-age=31536000, immutable
+
+# Generated Open Graph cards. Regenerated by scripts/og-cards.mjs under the same
+# names, so a week rather than a year — a stale share card is a live mistake.
+/img/social/*
+  Cache-Control: public, max-age=604800
+
+# The media pipeline emits these with width suffixes but no content hash.
+/img/photos/*
+  Cache-Control: public, max-age=2592000
+
+# ── Security headers ─────────────────────────────────────────────────────────
+#
+# HSTS and X-Content-Type-Options already arrive from the Cloudflare zone, not
+# from here — check both are still present after any SSL/TLS settings change,
+# because nothing in this repo would notice them disappearing.
+#
+# ⚠ WHAT THIS CSP DELIBERATELY DOES NOT DO: restrict scripts.
+# `script-src` is absent on purpose. Google Tag Manager exists to inject
+# arbitrary scripts chosen later by whoever runs the container, and this is a
+# static site, so per-request nonces are not available. Any workable
+# `script-src` would need `'unsafe-inline'` plus an allow-list of every origin
+# GTM might load — which blocks almost no real XSS while silently breaking the
+# next marketing tag the client adds. A CSP that gets switched off the first
+# time it breaks something protects nobody.
+#
+# What IS here are the directives that cost nothing and cannot break a working
+# page, verified against the live site before shipping:
+#   frame-ancestors  clickjacking — nothing embeds this site
+#   base-uri         stops an injected <base> rewriting every relative URL
+#   form-action      every form on the site posts to its own origin
+#   object-src       no plugins, no <object>, no Flash-era attack surface
+#
+# If a real script-src is ever wanted, ship it as Content-Security-Policy-
+# Report-Only FIRST, and watch the console on every route that embeds a
+# third-party surface — a booking widget, a chat bundle, a map, a review feed.
+# Those are what a script-src breaks, and they break silently. Only then
+# enforce.
+/*
+  Referrer-Policy: strict-origin-when-cross-origin
+  Permissions-Policy: camera=(), microphone=(), geolocation=(), interest-cohort=()
+  Content-Security-Policy: frame-ancestors 'self'; base-uri 'self'; form-action 'self'; object-src 'none'

package/template/public/_redirects

@@ -0,0 +1,39 @@
+# Legacy URL map. Hit counts are from the Rank Math redirections export
+# (e.g. dump/seo/rank-math-settings-*.json) — they are the difference between
+# "cleanup" and "deleting traffic". Nothing here points at the homepage when a
+# specific equivalent exists; search engines read that as a soft 404.
+
+# ── Carried over from Rank Math ──────────────────────────────────────────────
+# EXAMPLE, commented out because its target does not exist in a fresh template
+# and `npm run verify` correctly reports a 301 into a 404. Uncomment and point
+# it at a real route.
+#
+# Typo in an original slug, fixed later on the live site. Even at 0 recorded
+# hits the wrong spelling is still in the wild and in old sitemaps.
+#/exmaple-post-slug-with-a-typo  /example-post-slug-with-a-typo/  301
+
+# ── WordPress plumbing that no longer exists ─────────────────────────────────
+# These were live URLs on the old stack. Left to 404 they would show up in
+# Search Console as broken links from anything that ever scraped the site.
+/feed/                 /rss.xml   301
+/feed                  /rss.xml   301
+/comments/feed/        /rss.xml   301
+/sitemap_index.xml     /sitemap-index.xml   301
+/post-sitemap.xml      /sitemap-index.xml   301
+/page-sitemap.xml      /sitemap-index.xml   301
+/local-sitemap.xml     /sitemap-index.xml   301
+
+# Author archives were noindexed on the old site and have no equivalent here.
+# The blog index is the closest real page, not the homepage.
+/author/*              /blog/     301
+
+# Attachment pages. Rank Math already redirected these to the homepage
+# (`attachment_redirect_default`); the media library itself is gone. No rule
+# here on purpose — Cloudflare `_redirects` only accepts 200/301/302/303/307/308,
+# and these paths *should* 404 rather than 301 to a page that is not the image
+# someone asked for. The catch-all worker returns a real 404 for them.
+
+# ── Chrome ───────────────────────────────────────────────────────────────────
+# /projects/ and /privacy-policy/ were registered in WordPress but returned 404
+# on the live site — /privacy-policy/ now exists for real, /projects/ does not
+# and correctly 404s.

package/template/public/site.webmanifest

@@ -0,0 +1,13 @@
+{
+  "name": "Business Name",
+  "short_name": "Business",
+  "description": "What you do, in one sentence. Keep in sync with business.ts.",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#000000",
+  "icons": [
+    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
+    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" }
+  ]
+}

package/template/scripts/a11y-evidence.mjs

@@ -0,0 +1,258 @@
+/**
+ * Write the accessibility evidence pack.
+ *
+ *   npm run a11y:evidence                          # against .pa11yci.json (wrangler dev)
+ *   npm run a11y:evidence -- https://example.com   # against a deployed host
+ *
+ * Writes docs/a11y-evidence/<date>.md and leaves it for you to commit.
+ *
+ * ── WHY THIS EXISTS ────────────────────────────────────────────────────────
+ * `build.md` phase 9 requires an evidence pack and `compliance.md` §7 defines
+ * what counts. Nothing produced it: `npm run a11y` printed to a terminal and
+ * the output died with the scrollback. So the artefact that has value if anyone
+ * ever asks was the one artefact never written down.
+ *
+ * `compliance.md` §7, verbatim: *"Hand over the evidence, not the assertion.
+ * Dated tool output, which pages were tested manually and how, known gaps with
+ * an owner."* Three of those four are things a script cannot know.
+ *
+ * ── IT MUST NOT LOOK COMPLETE ──────────────────────────────────────────────
+ * Automated tooling catches roughly a third of issues, and about 42% of WCAG
+ * criteria cannot be machine-checked at all. A pack that listed a clean axe run
+ * and stopped would be worse than no pack: it reads as a finished audit, and it
+ * is the floor.
+ *
+ * So the manual layers are written in as UNCHECKED every time, with the date
+ * they were last done left blank for a human. The file is deliberately not
+ * signable until someone fills those in.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const RESET = '';
+const RED = '';
+const GREEN = '';
+const YELLOW = '';
+const DIM = '';
+const BOLD = '';
+
+const host = process.argv.slice(2).find((a) => a.startsWith('http'))?.replace(/\/$/, '');
+const OUT_DIR = 'docs/a11y-evidence';
+
+/*
+ * LOCAL date, not `toISOString()`.
+ *
+ * This is a record a person attests to having made, so it has to carry the date
+ * that person would write on it. `toISOString()` is UTC: on a machine at UTC+5
+ * it dates the pack YESTERDAY for the first five hours of every day, and on a
+ * machine behind UTC it dates it tomorrow for the last few. Either way the file
+ * is named a day off, the staleness comparison drifts with it, and the error is
+ * invisible because the date it prints is always plausible.
+ */
+const now = new Date();
+const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+
+const version = (pkg) => {
+  try {
+    return require(`${pkg}/package.json`).version;
+  } catch {
+    return 'unknown';
+  }
+};
+
+/* ── 1. Automated sweep ──────────────────────────────────────────────────── */
+
+console.log(`${BOLD}── pa11y-ci · WCAG2AA ${'─'.repeat(38)}${RESET}`);
+
+const config = JSON.parse(readFileSync('.pa11yci.json', 'utf8'));
+const standard = config.defaults?.standard ?? 'WCAG2AA';
+const runners = config.defaults?.runners ?? ['htmlcs'];
+
+const args = host
+  ? ['pa11y-ci', '--sitemap', `${host}/sitemap-index.xml`, '--standard', standard, '--json']
+  : ['pa11y-ci', '--config', '.pa11yci.json', '--json'];
+
+let report;
+try {
+  /* pa11y-ci exits non-zero when it finds errors, and still prints the JSON.
+     A non-zero exit here is a RESULT, not a failure to run. */
+  const out = execFileSync('npx', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  report = JSON.parse(out);
+} catch (error) {
+  const out = error.stdout?.toString() ?? '';
+  try {
+    report = JSON.parse(out);
+  } catch {
+    console.error(
+      `${RED}✗${RESET} pa11y-ci could not run.\n` +
+        `  ${DIM}Start the site first: npm run build:staging && npx wrangler dev${RESET}\n` +
+        `  ${(error.stderr?.toString() ?? '').slice(0, 400)}`,
+    );
+    process.exit(1);
+  }
+}
+
+const rows = Object.entries(report.results).map(([url, issues]) => ({
+  url,
+  errors: issues.filter((i) => i.type === 'error'),
+  warnings: issues.filter((i) => i.type === 'warning'),
+  notices: issues.filter((i) => i.type === 'notice'),
+}));
+
+for (const r of rows) {
+  const mark = r.errors.length ? `${RED}✗${RESET}` : `${GREEN}✓${RESET}`;
+  const path = new URL(r.url).pathname;
+  console.log(
+    `  ${mark} ${path.padEnd(28)} ${String(r.errors.length).padStart(2)} error(s)   ` +
+      `${DIM}${r.warnings.length} warning(s)${RESET}`,
+  );
+}
+
+/* ── 2. Reflow, which pa11y does not cover ───────────────────────────────── */
+
+console.log(`\n${BOLD}── reflow · 320px + 200% ${'─'.repeat(35)}${RESET}`);
+
+let reflowOut = '';
+let reflowOk = false;
+try {
+  reflowOut = execFileSync('node', ['scripts/check-reflow.mjs', ...(host ? [host] : [])], {
+    encoding: 'utf8',
+  });
+  reflowOk = true;
+} catch (error) {
+  reflowOut = (error.stdout?.toString() ?? '') + (error.stderr?.toString() ?? '');
+}
+const reflowSummary = reflowOut.trim().split('\n').filter(Boolean).slice(-1)[0] ?? 'did not run';
+console.log(`  ${reflowOk ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`} ${reflowSummary.replace(/\[[0-9;]*m/g, '')}`);
+
+/* ── 3. Is the published statement still telling the truth? ──────────────── */
+
+const statement = existsSync('src/pages/accessibility.astro')
+  ? readFileSync('src/pages/accessibility.astro', 'utf8')
+  : '';
+const reviewed = /const reviewed = '([^']+)'/.exec(statement)?.[1] ?? null;
+
+let staleWarning = null;
+if (reviewed) {
+  const parsed = new Date(reviewed);
+  if (!Number.isNaN(parsed.valueOf())) {
+    const days = Math.round((Date.now() - parsed.valueOf()) / 86400000);
+    if (days > 0) {
+      staleWarning =
+        `/accessibility says it was last reviewed ${reviewed} — ${days} day(s) ago.\n` +
+        `  This run is newer. Update \`reviewed\` in src/pages/accessibility.astro, or the\n` +
+        `  published page is making a testing claim about a site that has moved on.`;
+    }
+  }
+}
+
+/* ── 4. The pack ─────────────────────────────────────────────────────────── */
+
+const totalErrors = rows.reduce((n, r) => n + r.errors.length, 0);
+const target = host ?? 'http://localhost:8788 (wrangler dev)';
+
+const issueLines = rows
+  .filter((r) => r.errors.length)
+  .map(
+    (r) =>
+      `### ${new URL(r.url).pathname}\n\n` +
+      r.errors
+        .map(
+          (e) =>
+            `- **${e.code ?? 'unknown'}** — ${e.message}\n` +
+            `  - selector: \`${e.selector || '—'}\`\n` +
+            `  - runner: ${e.runner ?? '—'}\n` +
+            `  - owner: ⚠ · fixed by: ⚠`,
+        )
+        .join('\n'),
+  )
+  .join('\n\n');
+
+const pack = `# Accessibility evidence — ${today}
+
+Target: \`${target}\`
+Standard: **${standard}** · runners: ${runners.join(', ')}
+
+| Tool | Version |
+| --- | --- |
+| pa11y-ci | ${version('pa11y-ci')} |
+| pa11y | ${version('pa11y')} |
+| axe-core | ${version('axe-core')} |
+
+> **This is the floor, not an audit.** Automated tooling catches roughly a third of
+> issues by count, and about 42% of WCAG success criteria cannot be machine-checked at
+> all. The section below marked *not done by this run* is where the rest lives.
+
+---
+
+## 1. Automated — one URL per template family
+
+| Page | Errors | Warnings | Notices |
+| --- | --- | --- | --- |
+${rows
+  .map(
+    (r) =>
+      `| \`${new URL(r.url).pathname}\` | ${r.errors.length} | ${r.warnings.length} | ${r.notices.length} |`,
+  )
+  .join('\n')}
+
+**${totalErrors} error(s) across ${rows.length} page(s).**
+
+${issueLines || '_No errors at this standard._'}
+
+## 2. Reflow and resize — WCAG 1.4.10 and 1.4.4
+
+\`\`\`
+${reflowOut.replace(/\[[0-9;]*m/g, '').trim() || 'did not run'}
+\`\`\`
+
+## 3. NOT done by this run — a human has to, and has to date it
+
+⚠ **Fill these in or the pack is incomplete.** Each is a layer no tool covers, from
+\`compliance.md\` §7. One full pass on one page per template family, not every URL.
+
+| Layer | How | Done on | By |
+| --- | --- | --- | --- |
+| Keyboard | Tab, Shift-Tab, Enter, Space, Escape — hands off the mouse | ⚠ | ⚠ |
+| Screen reader | VoiceOver + Safari, or NVDA + Firefox | ⚠ | ⚠ |
+| Forms | Submit empty, submit bad, submit with JavaScript off | ⚠ | ⚠ |
+| Zoom | 200% and 400% | ⚠ | ⚠ |
+| Looked at it | On a real phone, at 100% | ⚠ | ⚠ |
+
+## 4. Known gaps
+
+⚠ **List them with an owner against each.** A documented gap is worth more than a clean
+claim — and never write "fully compliant", which is the claim that gets challenged.
+
+| Gap | Impact | Owner | Plan |
+| --- | --- | --- | --- |
+| ⚠ | ⚠ | ⚠ | ⚠ |
+
+---
+
+_Generated by \`npm run a11y:evidence\`. The published statement is at \`/accessibility\`;
+keep its \`reviewed\` date in step with the newest pack in this directory._
+`;
+
+mkdirSync(OUT_DIR, { recursive: true });
+const outPath = `${OUT_DIR}/${today}.md`;
+writeFileSync(outPath, pack);
+
+console.log(`\n${GREEN}✓${RESET} ${outPath}`);
+console.log(
+  `${DIM}  tool + version, date, per-family results, what was tested BY HAND (blank),\n` +
+    `  and known gaps with an owner (blank). Fill in §3 and §4, then commit it.${RESET}`,
+);
+
+if (staleWarning) console.log(`\n${YELLOW}⚠${RESET} ${staleWarning}`);
+
+/*
+ * Exit 0 even with errors found. This writes a RECORD; it is not a gate — the
+ * gate is `npm run a11y`, which fails the build. A generator that refused to
+ * write the evidence whenever the evidence was bad would only ever document
+ * sites that were already fine.
+ */

package/template/scripts/check-console.mjs

@@ -0,0 +1,125 @@
+/**
+ * Console errors and failed requests, on the DEPLOYED site.
+ *
+ *   npm run console                                # every route, localhost:8788
+ *   npm run console -- https://new.example.com     # a deployed host
+ *   npm run console -- --only=/contact/            # one route, substring match
+ *
+ * ── WHY THIS EXISTS ────────────────────────────────────────────────────────
+ * `build.md` §7 has carried this as a definition-of-done row from the start —
+ * *"zero console errors and zero failed requests on the deployed site"* — and
+ * the row says why nothing else can do it: **a blocked third-party script or a
+ * 404 asset is invisible to a status-code check.** The page returns 200. The
+ * HTML is correct. Something inside it failed after the response was complete.
+ *
+ * `npm run verify` deliberately uses only `fetch`, so it can never see this.
+ * That is the gap this closes, and it is why this is a separate script rather
+ * than another section there.
+ *
+ * ── WHAT COUNTS AS A FAILURE ───────────────────────────────────────────────
+ * Console *errors* and *failed requests* fail the run. Warnings are printed and
+ * do not, because third-party embeds produce warnings constantly and a check
+ * that goes red on someone else's deprecation notice gets switched off.
+ */
+
+import puppeteer from 'puppeteer';
+
+import { discoverRoutes } from './lib/routes.mjs';
+
+const RESET = '[0m';
+const RED = '[31m';
+const GREEN = '[32m';
+const YELLOW = '[33m';
+const DIM = '[2m';
+const BOLD = '[1m';
+
+const args = process.argv.slice(2);
+const only = (args.find((a) => a.startsWith('--only=')) ?? '').replace('--only=', '');
+const host = args.find((a) => !a.startsWith('--'));
+const BASE = (host ?? process.env.PUBLIC_SITE_URL ?? 'http://localhost:8788').replace(/\/$/, '');
+
+const { routes: discovered, source } = await discoverRoutes(BASE);
+const ROUTES = discovered
+  .map((url) => new URL(url).pathname)
+  .filter((r) => !only || only.split(',').some((f) => r.includes(f.trim())));
+
+if (!ROUTES.length) {
+  console.error(
+    `No routes for ${BASE}.\n  Build first (\`npm run build:staging\`), or pass a host that serves a sitemap.`,
+  );
+  process.exit(1);
+}
+
+console.log(`${BOLD}── Console and network ${'─'.repeat(36)}${RESET}`);
+console.log(`  ${DIM}${ROUTES.length} route(s) from ${source}, against ${BASE}${RESET}\n`);
+
+const browser = await puppeteer.launch({ args: ['--no-sandbox'] });
+const findings = [];
+let warnings = 0;
+
+try {
+  for (const route of ROUTES) {
+    const page = await browser.newPage();
+    const errors = [];
+    const failed = [];
+
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') errors.push(msg.text().slice(0, 200));
+      else if (msg.type() === 'warning') warnings++;
+    });
+    page.on('pageerror', (err) => errors.push(`uncaught: ${String(err).slice(0, 200)}`));
+    page.on('requestfailed', (req) => {
+      /* An aborted request is usually the navigation itself being replaced, not
+         a broken asset. Only report what actually could not be retrieved. */
+      const reason = req.failure()?.errorText ?? '';
+      if (/ERR_ABORTED/.test(reason)) return;
+      failed.push(`${reason}  ${req.url()}`);
+    });
+    page.on('response', (res) => {
+      if (res.status() >= 400) failed.push(`${res.status()}  ${res.url()}`);
+    });
+
+    try {
+      await page.goto(BASE + route, { waitUntil: 'networkidle0', timeout: 45000 });
+    } catch (e) {
+      errors.push(`navigation: ${e.name}`);
+    }
+
+    if (errors.length || failed.length) {
+      findings.push({ route, errors, failed });
+      console.log(`  ${RED}✗${RESET} ${route}`);
+      for (const e of errors) console.log(`      ${DIM}console  ${e}${RESET}`);
+      for (const f of failed) {
+        /* Browsers request /favicon.ico on their own when no icon is declared.
+           No markup causes it, so say what it actually means rather than
+           leaving someone hunting for the reference. */
+        const hint = /\/favicon\.ico$/.test(f)
+          ? '  ← the browser asks for this by itself; declare `icons` in src/data/site.ts'
+          : '';
+        console.log(`      ${DIM}request  ${f}${hint}${RESET}`);
+      }
+    } else {
+      console.log(`  ${GREEN}✓${RESET} ${route}`);
+    }
+
+    await page.close();
+  }
+} finally {
+  await browser.close();
+}
+
+if (warnings) {
+  console.log(`\n  ${YELLOW}!${RESET} ${warnings} console warning(s) — printed, not failed.`);
+  console.log(
+    `  ${DIM}Third-party embeds warn constantly. A check that goes red on someone else's\n` +
+      `  deprecation notice is a check that gets switched off.${RESET}`,
+  );
+}
+
+console.log(
+  findings.length
+    ? `\n${RED}✗ ${findings.length} route(s) with errors or failed requests${RESET}\n`
+    : `\n${GREEN}✓ no console errors and no failed requests across ${ROUTES.length} route(s)${RESET}\n`,
+);
+
+process.exit(findings.length ? 1 : 0);

package/template/scripts/check-env.mjs

@@ -0,0 +1,99 @@
+/**
+ * Refuse to ship a build whose environment does not match the domains it will
+ * be served on.
+ *
+ *   node scripts/check-env.mjs
+ *
+ * Runs at the end of `build:staging` and `build:production`, so it cannot be
+ * forgotten — including on Cloudflare Workers Builds, where the build command
+ * is typed once into a settings dialog and then never looked at again.
+ *
+ * ── THE FAILURE THIS EXISTS FOR ────────────────────────────────────────────
+ * `PUBLIC_SITE_ENV` decides indexability, canonical host, which KV namespace
+ * leads land in, and whether analytics is emitted at all. `wrangler.jsonc`
+ * decides which domains answer. Nothing connects the two.
+ *
+ * At go-live, two edits have to happen together: the routes gain
+ * example.com, and the build command becomes `build:production`. Do
+ * the first and forget the second and the live site ships with `noindex` on
+ * every page, canonicals pointing at the staging host, leads written to
+ * LEADS_STAGING, and no analytics.
+ *
+ * It would look perfect. It would be invisible to Google, and every enquiry
+ * would go to the wrong place. Nothing in a build log or a page would say so.
+ *
+ * The reverse — a production build served only on the staging host — is the
+ * other half: an indexable duplicate of the real site.
+ */
+
+import { readFileSync } from 'node:fs';
+
+const RESET = '';
+const RED = '';
+const GREEN = '';
+
+/** wrangler.jsonc is JSON with comments; strip them rather than add a parser. */
+function readWrangler() {
+  const raw = readFileSync('wrangler.jsonc', 'utf8')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:"'])\/\/.*$/gm, '$1')
+    .replace(/,(\s*[}\]])/g, '$1');
+  return JSON.parse(raw);
+}
+
+const env = process.env.PUBLIC_SITE_ENV ?? 'development';
+const wrangler = readWrangler();
+const patterns = (wrangler.routes ?? []).map((r) => (typeof r === 'string' ? r : r.pattern));
+
+/* The production host is the apex, or www — NOT the staging subdomain, which
+   also ends in the same string. Matching on `.includes()` alone would treat
+   new.example.com as production.
+
+   A custom domain is a bare hostname ("new.example.com"); a ROUTE
+   carries a path ("example.com/*"). Go-live uses routes, so the path
+   is stripped before matching — without this the guard would look at
+   "example.com/*", fail to match, and conclude a production build
+   was pointed at staging-only routes. It would have blocked the cutover. */
+const hostOf = (p) => String(p).split('/')[0];
+/*
+ * ⚠ SET THIS PER PROJECT. It must match the production apex, with or without
+ *   `www.` — and must NOT match the staging subdomain, which ends in the same
+ *   string. Keep it in step with `PRODUCTION_HOSTS` in src/data/site.ts; those
+ *   two disagreeing is the failure this whole script exists to catch.
+ */
+const PRODUCTION_HOST = /^(www\.)?example\.com$/;
+
+const isProdHost = (p) => PRODUCTION_HOST.test(hostOf(p));
+const routesProduction = patterns.some(isProdHost);
+const routesStagingOnly = patterns.length > 0 && !routesProduction;
+
+const problems = [];
+
+if (routesProduction && env !== 'production') {
+  problems.push(
+    `wrangler.jsonc routes the PRODUCTION domain (${patterns.filter(isProdHost).join(', ')}) ` +
+      `but this build is PUBLIC_SITE_ENV=${env}.\n` +
+      `    That ships noindex on every page, canonicals pointing at the staging host,\n` +
+      `    leads written to LEADS_STAGING, and no analytics — on the live site.\n` +
+      `    Fix: build with \`npm run build:production\`.`,
+  );
+}
+
+if (routesStagingOnly && env === 'production') {
+  problems.push(
+    `This is a PRODUCTION build, but wrangler.jsonc only routes ${patterns.join(', ')}.\n` +
+      `    An indexable production build answering on the staging host is a duplicate\n` +
+      `    of the real site. Fix: add the production routes, or build with\n` +
+      `    \`npm run build:staging\`.`,
+  );
+}
+
+if (problems.length) {
+  console.error(`\n${RED}✗ environment does not match the deploy target${RESET}\n`);
+  for (const p of problems) console.error(`  ${p}\n`);
+  process.exit(1);
+}
+
+console.log(
+  `${GREEN}✓${RESET} PUBLIC_SITE_ENV=${env} matches routes: ${patterns.join(', ') || '(none)'}`,
+);