create-website-build-kit 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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,42 @@ 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".**

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/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/src/data/lastmod.json

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