create-website-build-kit 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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/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-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/lastmod.mjs

@@ -31,12 +31,15 @@
  */
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 
 const OUT = 'src/data/lastmod.json';
 
-const git = (args) =>
-  execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+const gitRaw = (args) =>
+  execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+
+/** Trimmed — correct for a single scalar like `--format=%cI` or a rev-parse answer. */
+const git = (args) => gitRaw(args).trim();
 
 if (git(['rev-parse', '--is-shallow-repository']) === 'true') {
   console.error(
@@ -47,8 +50,22 @@ if (git(['rev-parse', '--is-shallow-repository']) === 'true') {
 }
 
 /** Files with uncommitted changes. Their real "last modified" is now, not their last commit. */
+/*
+ * ⚠ gitRaw, NOT git — `--porcelain` LINES BEGIN WITH A SIGNIFICANT SPACE.
+ *
+ * The status format is two columns then a space: ` M path` for an unstaged
+ * modification. Trimming the whole output eats the leading space of the FIRST
+ * line only, so `slice(3)` then cut one character too far and produced
+ * "rc/pages/about.astro". That path matched nothing, so the first uncommitted
+ * file was never treated as dirty and kept its old commit date — while the
+ * script still printed "1 uncommitted file(s) dated today".
+ *
+ * Only the first entry, and only when it starts with a space, which is the
+ * ordinary case of having edited a page without committing it: the page most
+ * worth recrawling is the one that silently keeps a stale date.
+ */
 const dirty = new Set(
-  git(['status', '--porcelain'])
+  gitRaw(['status', '--porcelain'])
     .split('\n')
     .filter(Boolean)
     .map((l) => l.slice(3).trim()),
@@ -139,6 +156,9 @@ for (const [route, files] of [...sources].sort()) {
   if (date) out[route] = date;
 }
 
+/* src/data/ exists in the template, but not in a bare checkout or a fixture —
+   and an ENOENT stack is not a diagnosis. */
+mkdirSync(OUT.slice(0, OUT.lastIndexOf('/')), { recursive: true });
 writeFileSync(OUT, JSON.stringify(out, null, 2) + '\n');
 
 const spread = Object.values(out).reduce((m, d) => m.set(d, (m.get(d) ?? 0) + 1), new Map());

package/template/scripts/og-cards.mjs

@@ -185,7 +185,18 @@ function worstContrast(image, fgHex, [x, y, w, h]) {
 
 /* ── Drawing ───────────────────────────────────────────────────────────── */
 
-const manifest = JSON.parse(readFileSync('src/data/image-manifest.json', 'utf8'));
+/*
+ * ⚠ LAZY, BECAUSE A TOP-LEVEL READ RUNS BEFORE preflight().
+ *
+ * As a `const` at module scope this executed at import time — before main()
+ * called preflight() — so a project without an image manifest died on a raw
+ * ENOENT stack instead of being told its config was still the stub. The
+ * preflight exists precisely to name what is missing, and it was unreachable
+ * for the most common way to be missing something.
+ */
+let manifestCache = null;
+const manifest = () =>
+  (manifestCache ??= JSON.parse(readFileSync('src/data/image-manifest.json', 'utf8')));
 
 /**
  * Render one text run as its own transparent layer.
@@ -225,7 +236,7 @@ function buildCard(card, fonts, mark) {
 
   /* 1. Background. */
   if (card.photo) {
-    const entry = manifest[card.photo];
+    const entry = manifest()[card.photo];
     if (!entry) throw new Error(`${card.route ?? slug}: no manifest entry for "${card.photo}"`);
     const file = join('public', entry.src);
     if (!existsSync(file)) throw new Error(`${card.route ?? slug}: missing file ${file}`);

package/template/scripts/tells.mjs

@@ -238,6 +238,81 @@ tell(
   );
 }
 
+/*
+ * ── THE TELLS OF A GENERATED SITE, NOT A TEMPLATED ONE ─────────────────────
+ *
+ * Everything above catches the 2015 agency template: three equal cards, body
+ * text at container width, a headline at 96px. This block catches a newer and
+ * closer failure — the house style of the thing writing the code.
+ *
+ * These are counts with generous thresholds, deliberately. One frosted header
+ * is a decision; three glass surfaces is an aesthetic nobody chose. A gate that
+ * fires on a single legitimate use is one people learn to switch off, which is
+ * how the first version of `check:refs` shipped with seven false positives on a
+ * clean tree.
+ */
+
+/*
+ * "glass everywhere" — backdrop-filter as a look rather than a decision.
+ *
+ * ⚠ THE CHARACTER CLASS EXCLUDES `}` AS WELL AS `;`, AND NONE OF THESE THREE
+ *   REQUIRE A TRAILING SEMICOLON. The last declaration in a block may legally
+ *   omit it. Written as `[^;]+;` these matched nothing there; written greedily
+ *   as `[^;]*` one match ran across two whole declarations and counted them as
+ *   one. Both were caught by fixtures asserting the check FIRES, never by the
+ *   clean template, where all three read as passing.
+ */
+{
+  const glass = [...sourceCss.matchAll(/backdrop-filter:[^;}]*blur/g)].length;
+  tell(
+    'frosted glass on more than one surface',
+    glass > 1,
+    `${glass} backdrop-filter blurs. One translucent header is a choice; a page of them is the default look of generated UI, and each one costs a paint.`,
+  );
+}
+
+/*
+ * "giant border radii" — 24px and up.
+ *
+ * ⚠ A pill and a circle are NOT this. `9999px`, `50%` and `100%` are how you
+ *   write "fully round" for a badge or an avatar, and flagging those would make
+ *   the check useless on any correct design.
+ */
+{
+  const radii = [...sourceCss.matchAll(/border-radius:\s*([^;}]+)/g)]
+    .flatMap((m) => [...m[1].matchAll(/([\d.]+)(px|rem)/g)])
+    .map((m) => (m[2] === 'rem' ? Number(m[1]) * 16 : Number(m[1])))
+    .filter((px) => px >= 24 && px < 200);
+  tell(
+    'border radii of 24px and up, repeatedly',
+    radii.length > 2,
+    `${radii.length} radii at 24px or more (${[...new Set(radii)].slice(0, 4).join(', ')}px). Softness at that scale reads as a default rather than a decision. Pills and circles are excluded.`,
+  );
+}
+
+/*
+ * "glow" — a shadow with no offset and a real blur. `0 0 40px <colour>` is
+ * decoration; nothing in the physical world lights up from behind.
+ *
+ * ⚠ A focus ring is `0 0 0 3px` — zero blur. Requiring blur ≥ 16px is what
+ *   keeps this from flagging the one shadow every accessible site needs.
+ */
+{
+  const glows = [...sourceCss.matchAll(/box-shadow:\s*([^;}]+)/g)]
+    .flatMap((m) => m[1].split(','))
+    .filter((sh) => /(^|\s)0\s+0\s+([\d.]+)(px|rem)/.test(sh))
+    .filter((sh) => {
+      const m = /(^|\s)0\s+0\s+([\d.]+)(px|rem)/.exec(sh);
+      const blur = m[3] === 'rem' ? Number(m[2]) * 16 : Number(m[2]);
+      return blur >= 16;
+    });
+  tell(
+    'glow shadows',
+    glows.length > 0,
+    `${glows.length} zero-offset shadow(s) with a large blur. A glow is decoration with no physical referent; a shadow with offset reads as light. Focus rings (0 0 0 3px) are excluded.`,
+  );
+}
+
 // "the 404, the empty state or the form's invalid state was never designed"
 tell(
   'no invalid / busy form state',

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. ' +