create-website-build-kit 0.1.3 → 0.1.5

package/package.json

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

@@ -505,7 +505,12 @@ In this order. Steps 1–3 happen days ahead, not on launch day.
    ```bash
    npm run verify -- "https://$PROD"
    npm run check:sitemap          # after a production build: nothing listed AND noindex
+   npm run check:secrets          # the production worker holds every declared secret
    ```
+
+   `check:secrets` already ran as part of `deploy:production`. Run it again here because
+   go-live is when it is most likely to fail: a secret set on the staging worker is not
+   automatically on this one, and the failure is silent — leads store, nothing emails.
 9. **Submit the sitemap** in [Search Console](https://search.google.com/search-console) and
    [Bing Webmaster Tools](https://www.bing.com/webmasters). If you kept the old filename, the
    existing entry keeps working and there is nothing to resubmit.

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/package.json

@@ -25,15 +25,16 @@
     "recon": "node scripts/recon.mjs",
     "extract": "node scripts/extract.mjs",
     "dns": "node scripts/dns-snapshot.mjs",
-    "seo": "npx --yes github:nurkamol/seo-audit",
+    "seo": "npx --yes @nurkamol/seo-audit@1",
     "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"
+    "deploy:staging": "npm run build:staging && wrangler deploy && node scripts/check-secrets.mjs",
+    "deploy:production": "npm run build:production && wrangler deploy && node scripts/check-secrets.mjs",
+    "check:secrets": "node scripts/check-secrets.mjs"
   },
   "dependencies": {
     "@astrojs/cloudflare": "^14.1.7",

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

@@ -0,0 +1,152 @@
+/**
+ * Refuse to call a deploy finished when the worker is missing a secret.
+ *
+ *   npm run check:secrets
+ *
+ * Runs at the end of `deploy:staging` and `deploy:production`, after the deploy
+ * rather than before it — a worker that does not exist yet cannot be missing
+ * anything, and the first deploy is exactly when a secret has never been set.
+ *
+ * ── THE FAILURE THIS EXISTS FOR ────────────────────────────────────────────
+ * `secret()` in src/lib/runtime.ts returns `undefined` for a binding that was
+ * never set. Nothing throws. The contact form still validates, still stores the
+ * lead in KV, still returns 200, and still shows the visitor a thank-you.
+ *
+ * The API says `{"stored":true,"emailed":false}` and nobody reads API responses.
+ *
+ * So the site captures enquiries and notifies no one. There is no error, no
+ * failed request, no console warning, and nothing in the deploy log. It is found
+ * weeks later, by someone asking why the phone stopped ringing — and the leads
+ * are all still sitting in KV, which is the only reason this is recoverable.
+ *
+ * ⚠ THIS IS NOT HYPOTHETICAL. It shipped that way on the ochome build: deployed,
+ *   verified green by `npm run verify`, storing leads, emailing nothing.
+ *   `verify` lists it under "what this cannot see", which is honest and did not
+ *   help — a note in a report nobody re-reads is not a gate.
+ *
+ * ── WHAT IT COMPARES ───────────────────────────────────────────────────────
+ * `.dev.vars.example` is the declared contract: every secret the code expects,
+ * committed, with placeholder values. `wrangler secret list` is what the
+ * deployed worker actually holds. The two disagreeing is the bug.
+ *
+ * Using the example file rather than a list hardcoded here means adding a
+ * secret to the code and to the example — which you must do anyway, or local
+ * `wrangler dev` breaks — extends this check for free. A hardcoded list would
+ * go stale silently, the way `check-env.mjs` did.
+ */
+
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const DIM = '\x1b[2m';
+const YELLOW = '\x1b[33m';
+
+/* `npx` is `npx.cmd` on Windows and execFileSync cannot resolve it without a
+   shell. Windows is a supported target and this is the second script to need
+   the line. */
+const WIN = process.platform === 'win32';
+
+/** Every NAME= in .dev.vars.example, which is the list the code expects. */
+function declaredSecrets() {
+  let raw;
+  try {
+    raw = readFileSync('.dev.vars.example', 'utf8');
+  } catch {
+    console.error(
+      `\n${RED}✗ .dev.vars.example not found${RESET}\n\n` +
+        '  It is the declared list of secrets this site needs, and this check\n' +
+        '  has nothing to compare against without it. Run from the project root.\n',
+    );
+    process.exit(1);
+  }
+  return [...raw.matchAll(/^\s*([A-Z][A-Z0-9_]*)\s*=/gm)].map((m) => m[1]);
+}
+
+/**
+ * Secrets on the deployed worker.
+ *
+ * Returns null — not an empty list — when the worker does not exist yet, so a
+ * pre-deploy state is never reported as "every secret is missing".
+ */
+function deployedSecrets() {
+  let out;
+  try {
+    out = execFileSync(WIN ? 'npx.cmd' : 'npx', ['wrangler', 'secret', 'list'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: WIN,
+    });
+  } catch (err) {
+    const text = `${err.stdout ?? ''}${err.stderr ?? ''}`;
+    /* A worker that has never been deployed, versus a real problem — being
+       logged out, or offline. Only the first is not a failure. */
+    if (/script_not_found|workers\.api\.error\.script_not_found|10007|not found/i.test(text)) {
+      return null;
+    }
+    console.error(
+      `\n${RED}✗ could not read the worker's secrets${RESET}\n\n` +
+        `${text.trim().split('\n').slice(-6).map((l) => `  ${l}`).join('\n')}\n\n` +
+        '  Usually `wrangler login`. This check cannot pass without an answer —\n' +
+        '  it refuses rather than assume the secrets are fine.\n',
+    );
+    process.exit(1);
+  }
+  /* wrangler prints a banner before the JSON. Take the array, not the noise. */
+  const match = out.match(/\[[\s\S]*\]/);
+  if (!match) return [];
+  try {
+    return JSON.parse(match[0]).map((s) => s.name);
+  } catch {
+    return [];
+  }
+}
+
+const declared = declaredSecrets();
+if (!declared.length) {
+  console.log(`${DIM}· .dev.vars.example declares no secrets — nothing to check${RESET}`);
+  process.exit(0);
+}
+
+const deployed = deployedSecrets();
+
+if (deployed === null) {
+  console.log(
+    `${DIM}· worker not deployed yet — nothing to check${RESET}\n` +
+      `${DIM}  ${declared.length} secret(s) will be required once it is: ${declared.join(', ')}${RESET}`,
+  );
+  process.exit(0);
+}
+
+const missing = declared.filter((name) => !deployed.includes(name));
+const extra = deployed.filter((name) => !declared.includes(name));
+
+if (missing.length) {
+  console.error(`\n${RED}✗ the deployed worker is missing ${missing.length} secret(s)${RESET}\n`);
+  for (const name of missing) {
+    console.error(`    ${name}`);
+  }
+  console.error(
+    `\n  The deploy succeeded. The site is live and INCOMPLETE — whatever reads\n` +
+      `  these gets \`undefined\` and carries on silently. If BREVO_API_KEY is in\n` +
+      `  the list, the form is storing leads and emailing nobody.\n\n` +
+      `  Set them, then deploy again:\n\n` +
+      missing.map((n) => `    npx wrangler secret put ${n}`).join('\n') +
+      '\n',
+  );
+  process.exit(1);
+}
+
+if (extra.length) {
+  /* Not a failure — a secret the code no longer reads is dead weight, not a
+     broken site. Worth saying once, because it is usually a rename that only
+     got done on one side. */
+  console.log(
+    `${YELLOW}!${RESET} on the worker but not in .dev.vars.example: ${extra.join(', ')}\n` +
+      `${DIM}  either the code stopped reading it, or the example was never updated${RESET}`,
+  );
+}
+
+console.log(`${GREEN}✓${RESET} every declared secret is set: ${declared.join(', ')}`);

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/scripts/verify.mjs

@@ -1051,7 +1051,7 @@ const warned = results.filter((r) => !r.ok && r.warn);
 console.log(`\n${BOLD}── What this cannot see ${'─'.repeat(36)}${RESET}`);
 for (const line of [
   'One pageview per visit — a double-count is only visible in Realtime',
-  'That a valid submission stores AND emails — send one by hand, once',
+  'That a valid submission stores AND emails — send one by hand, once (`npm run check:secrets` covers whether the key is even set)',
   'Whether the analytics container is the client\'s own — fetch it and read it',
   'Whether a redirect target is the RIGHT page, only that it resolves',
   'How fast it FEELS — weight and blocking counts are the inputs, never a timing. ' +