create-website-build-kit 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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/docs/traps.md

@@ -930,3 +930,77 @@ Worth knowing before you go hunting: this got *more* visible when the run starte
 covering both colour schemes, because that doubles the number of Chrome sessions
 and so doubles the chances of hitting the race. The change that surfaced it was
 not the change that caused it.
+
+### A script throws `ReferenceError` for something nothing ever imported
+
+**Symptom:** `npm run recon` runs the whole crawl, prints its sitemap and URL
+sections, and then dies at the last one:
+
+```
+const PRESERVE = PRESERVED;
+                 ^
+ReferenceError: PRESERVED is not defined
+```
+
+The file imports two things and uses a third. It shipped in a published package
+and a user hit it on a real migration, on Windows, on the first command the
+documentation tells you to run.
+
+**Why nothing caught it.** This is the important part, because the instinct is
+that surely *something* would have:
+
+| | |
+| --- | --- |
+| `node --check` | Parses. An undefined identifier is **valid syntax** |
+| `astro check` | Types `.astro` and `.ts`. The scripts are standalone `.mjs` |
+| CI | Runs the build. `recon` needs a live site, so CI never runs it |
+| Smoke-running it | The throw is on line 302, reached only after the crawl — tested, and a `--help` load-check passes the broken file |
+
+**Fix:** import it. The real fix is the gate — `npm run check:refs` cross-checks
+every name `scripts/lib/*.mjs` exports against every script that uses one, and
+fails when a use has no import.
+
+**The first version of that gate was worse than none.** It flagged every
+SCREAMING_CASE identifier that was never bound, and produced seven false
+positives on a clean tree: `WCAG` and `CAA` in prose, `ERR_ABORTED` inside a
+regex literal, `AND` in a comment. Stripping comments and strings with regexes
+is a losing game without a parser. Narrowing it to names the libs actually
+export removed the guesswork — prose never collides with a real export.
+
+**A checker with false positives gets switched off, and then its silence means
+"nobody looked" rather than "nothing wrong".**
+
+### A checker that counts source AND build output counts everything twice
+
+**Symptom:** `npm run tells` reports *"3 auto-fill/auto-fit minmax grids"* on a
+project whose entire source contains **one**. The threshold is "more than
+twice", so a single grid fails the check. Removing grids does not help — the
+count only drops when you get to zero.
+
+`tells.mjs` reads `allCss = [...styleFiles, ...distCss]`, and including the
+built stylesheets is deliberate and right *for presence tests*: a rule that
+never reaches the build is not a rule the site has. It is wrong for **counting**.
+Astro inlines shared CSS into every entry bundle, so one rule in `project.css`
+is read once from source and again from each built stylesheet:
+
+```
+1×  src/styles/project.css
+1×  dist/client/_astro/Base.U1P5p-HP.css
+1×  dist/client/_astro/contact.D3DAZGAV.css
+```
+
+One rule, three matches, against a threshold of two.
+
+**Fix:** count from source only. `tells.mjs` now builds a separate `sourceCss`
+for the three tells that count rather than test presence — the grid count, the
+long-animation count and the stripped-focus-ring count. The presence tests keep
+reading the built CSS, because for those the build output is the point.
+
+**Why it hid for so long:** the other two counting tells threshold at `> 0`, so
+duplication inflated their *reported number* without ever changing the verdict.
+Only the grid tell compares against a number greater than one, and only that one
+gave a wrong answer. The bug was in all three the whole time.
+
+The general shape is worth keeping: **a checker that reads both a source and a
+generated copy of that source is counting the same thing more than once.** If
+its threshold is anything other than "any", it is wrong.

package/template/scripts/a11y-evidence.mjs

@@ -89,6 +89,14 @@ const runners = config.defaults?.runners ?? ['htmlcs'];
  * was tested when half of it was not is the thing somebody hands to a lawyer.
  * See scripts/lib/schemes.mjs.
  */
+/*
+ * ⚠ `shell: true` ON WINDOWS, and it is not optional there. `npx` is
+ * `npx.cmd`, and execFileSync does not resolve .cmd without a shell — it
+ * fails ENOENT, which reads as "npx is not installed" on a machine where it
+ * plainly is. Left off on POSIX, where a shell buys nothing and costs quoting.
+ */
+const WIN = process.platform === 'win32';
+
 const tmp = mkdtempSync(join(tmpdir(), 'a11y-evidence-'));
 
 const runScheme = (scheme) => {
@@ -104,7 +112,9 @@ const runScheme = (scheme) => {
   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. */
-    return JSON.parse(execFileSync('npx', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }));
+    return JSON.parse(
+      execFileSync('npx', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, shell: WIN }),
+    );
   } catch (error) {
     const out = error.stdout?.toString() ?? '';
     try {

package/template/scripts/check-a11y.mjs

@@ -28,6 +28,14 @@ const GREEN = '\x1b[32m';
 const DIM = '\x1b[2m';
 const BOLD = '\x1b[1m';
 
+/*
+ * ⚠ `shell: true` ON WINDOWS, and it is not optional there. `npx` is
+ * `npx.cmd`, and execFileSync does not resolve .cmd without a shell — it
+ * fails ENOENT, which reads as "npx is not installed" on a machine where it
+ * plainly is. Left off on POSIX, where a shell buys nothing and costs quoting.
+ */
+const WIN = process.platform === 'win32';
+
 const CONFIG = '.pa11yci.json';
 if (!existsSync(CONFIG)) {
   console.error(`${RED}✗${RESET} ${CONFIG} not found — run this from the site root.`);
@@ -58,7 +66,7 @@ for (const scheme of schemes) {
 
   console.log(`${BOLD}${scheme}${RESET}`);
   try {
-    execFileSync('npx', ['pa11y-ci', '--config', file], { stdio: 'inherit' });
+    execFileSync('npx', ['pa11y-ci', '--config', file], { stdio: 'inherit', shell: WIN });
     console.log(`  ${GREEN}✓${RESET} ${scheme} clean\n`);
   } catch {
     failed++;

package/template/scripts/check-env.mjs

@@ -11,7 +11,8 @@
  * ── 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.
+ * decides which domains answer. Nothing connects the two — this script is the
+ * only thing that does, so it needs no per-project editing to work.
  *
  * At go-live, two edits have to happen together: the routes gain
  * example.com, and the build command becomes `build:production`. Do
@@ -56,14 +57,68 @@ const patterns = (wrangler.routes ?? []).map((r) => (typeof r === 'string' ? r :
    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.
+ * The production hostnames come from src/data/site.ts — the same list the site
+ * itself uses to decide indexability, canonicals and which KV namespace leads
+ * land in. NOT a copy of it.
+ *
+ * ── WHY THIS IS NOT A CONSTANT HERE ────────────────────────────────────────
+ * It used to be one, with a comment saying to keep it in step with site.ts.
+ * On the first real project it was not: site.ts had the client's domain, this
+ * file still had the template's example.com. So the guard matched nothing,
+ * called every deploy fine, and passed for the whole build — a guard that
+ * always passes is worse than none, because it reads as a check that ran.
+ *
+ * The drift WAS the failure this script exists to catch, reproduced inside the
+ * script. One source of truth is the only fix that holds; a sterner comment
+ * would not have survived the same afternoon.
+ *
+ * site.ts is TypeScript and imports `import.meta.env`, so node cannot import
+ * it. Read the literal out instead — same reasoning as stripping comments from
+ * wrangler.jsonc above rather than adding a parser.
  */
-const PRODUCTION_HOST = /^(www\.)?example\.com$/;
+function readProductionHosts() {
+  let src;
+  try {
+    src = readFileSync('src/data/site.ts', 'utf8');
+  } catch {
+    /* An ENOENT stack trace is not an answer to someone mid-deploy. It also
+       usually means the script is being run from the wrong directory. */
+    console.error(
+      `\n${RED}✗ src/data/site.ts not found${RESET}\n\n` +
+        '  This guard reads the production hostnames from it. Run it from the\n' +
+        '  project root — `npm run build:staging` and `build:production` do.\n',
+    );
+    process.exit(1);
+  }
+  const m = /export const PRODUCTION_HOSTS\s*=\s*\[([^\]]*)\]/.exec(src);
+  /* A guard that cannot find its own input must FAIL, never pass quietly —
+     that is the whole lesson above, and it applies to this branch too. */
+  if (!m) {
+    console.error(
+      `\n${RED}✗ cannot read PRODUCTION_HOSTS from src/data/site.ts${RESET}\n\n` +
+        '  This guard derives the production hostnames from that export. Without it\n' +
+        '  it cannot tell a production deploy from a staging one, so it refuses to\n' +
+        '  pass rather than wave the build through.\n\n' +
+        "  Expected a line like:  export const PRODUCTION_HOSTS = ['example.com'] as const;\n",
+    );
+    process.exit(1);
+  }
+  const hosts = [...m[1].matchAll(/['"]([^'"]+)['"]/g)].map((h) => h[1].toLowerCase());
+  if (!hosts.length) {
+    console.error(
+      `\n${RED}✗ PRODUCTION_HOSTS in src/data/site.ts is empty${RESET}\n\n` +
+        '  Every deploy would read as staging, including the production one.\n',
+    );
+    process.exit(1);
+  }
+  return hosts;
+}
+
+/* Exact membership, never a suffix match — `new.example.com` ends in
+   `example.com` and is NOT production. Same rule as isProductionHost(). */
+const PRODUCTION_HOSTS = readProductionHosts();
 
-const isProdHost = (p) => PRODUCTION_HOST.test(hostOf(p));
+const isProdHost = (p) => PRODUCTION_HOSTS.includes(hostOf(p).toLowerCase());
 const routesProduction = patterns.some(isProdHost);
 const routesStagingOnly = patterns.length > 0 && !routesProduction;
 

package/template/scripts/og-cards.mjs

@@ -64,6 +64,14 @@ function have(bin, args = ['--version']) {
   }
 }
 
+/** The install line for the platform this is actually running on. */
+const hint = (brew, winget, apt) =>
+  process.platform === 'win32'
+    ? `winget install ${winget}`
+    : process.platform === 'linux'
+      ? `sudo apt install ${apt}`
+      : `brew install ${brew}`;
+
 function preflight() {
   const missing = [];
 
@@ -83,9 +91,12 @@ function preflight() {
   }
 
   const tools = [
-    ['magick', ['-version'], 'ImageMagick', 'brew install imagemagick'],
-    ['rsvg-convert', ['--version'], 'rsvg-convert', 'brew install librsvg'],
-    ['python3', ['--version'], 'Python 3', 'brew install python'],
+    /* Per-platform. "brew install" on Windows is not a hint, it is a dead
+       end — and this preflight exists precisely so a missing tool names its
+       own fix. */
+    ['magick', ['-version'], 'ImageMagick', hint('imagemagick', 'ImageMagick.ImageMagick', 'imagemagick')],
+    ['rsvg-convert', ['--version'], 'rsvg-convert', hint('librsvg', 'GNOME.Librsvg', 'librsvg2-bin')],
+    ['python3', ['--version'], 'Python 3', hint('python', 'Python.Python.3.12', 'python3')],
   ];
   for (const [bin, args, label, install] of tools) {
     if (!have(bin, args)) {

package/template/scripts/recon.mjs

@@ -28,6 +28,7 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 
 import { GONE_TAG } from './lib/inventory.mjs';
+import { PRESERVED } from './lib/preserved.mjs';
 
 const RESET = '';
 const RED = '';
@@ -299,11 +300,9 @@ if (goneList.length) {
 /* ── 3. Paths other systems point at ──────────────────────────────────── */
 section('Preserved paths');
 
-const PRESERVE = PRESERVED;
-
 /* Manual redirects again: "serves a feed" and "301s to a feed" are different
    facts, and only the first means the path must be reproduced. */
-const preserved = await pool(PRESERVE, async ([path, why]) => {
+const preserved = await pool(PRESERVED, async ([path, why]) => {
   const r = await req(`${ORIGIN}${path}`, { method: 'HEAD', redirect: 'manual' });
   return { path, why, status: r?.status ?? 0, location: r?.headers.get('location') ?? '' };
 });

package/template/scripts/tells.mjs

@@ -64,6 +64,19 @@ const componentCss = componentFiles
   .flatMap((source) => [...source.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/g)].map((m) => m[1]))
   .join('\n');
 const everyCss = allCss + '\n' + componentCss;
+
+/*
+ * ⚠ SOURCE ONLY, FOR ANYTHING THAT COUNTS. `allCss` deliberately includes the
+ * built stylesheets, which is right for presence tests — a rule that never
+ * reaches the build is not a rule the site has. It is wrong for counting: Astro
+ * inlines the same CSS into every entry bundle, so ONE rule in project.css is
+ * read once from source and again from each built stylesheet.
+ *
+ * That made the auto-fill grid tell fire on a single grid — 1 rule counted as
+ * 3, against a threshold of "more than twice". The tell was telling the truth
+ * about its own arithmetic and nothing about the site.
+ */
+const sourceCss = styleFiles.map(read).join('\n') + '\n' + componentCss;
 /**
  * Raw component source, not just its <style> blocks. Inline `style=`
  * attributes are exactly where a card grid gets written when someone is
@@ -144,7 +157,7 @@ tell(
 // "three equal cards, centred, more than twice on one page"
 {
   const grids = [
-    ...(everyCss + componentSource).matchAll(/repeat\(\s*auto-(fill|fit)\s*,\s*minmax/g),
+    ...(sourceCss + componentSource).matchAll(/repeat\(\s*auto-(fill|fit)\s*,\s*minmax/g),
   ].length;
   tell(
     'the auto-fill card grid, more than twice',
@@ -185,7 +198,7 @@ tell(
 
 // "any animation runs longer than ~400ms"
 {
-  const slow = [...everyCss.matchAll(/(?:transition|animation)(?:-duration)?:[^;]*?(\d{3,4})ms/g)]
+  const slow = [...sourceCss.matchAll(/(?:transition|animation)(?:-duration)?:[^;]*?(\d{3,4})ms/g)]
     .map((m) => Number(m[1]))
     .filter((ms) => ms > 400);
   tell(
@@ -197,7 +210,7 @@ tell(
 
 // "focus rings are the browser default, or removed"
 {
-  const stripped = [...everyCss.matchAll(/outline:\s*(none|0)\b/g)].length;
+  const stripped = [...sourceCss.matchAll(/outline:\s*(none|0)\b/g)].length;
   const restored = /:focus-visible[^{]*\{[^}]*outline:/.test(everyCss);
   tell(
     'focus ring removed and not replaced',

package/template/src/data/lastmod.json

@@ -1 +1,5 @@
-{}
+{
+  "/": "2026-08-26",
+  "/accessibility/": "2026-08-26",
+  "/contact/": "2026-08-26"
+}