create-website-build-kit 0.1.3 → 0.1.4

package/package.json

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

@@ -969,3 +969,38 @@ 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/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/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',