create-website-build-kit 0.1.5 → 0.1.7

package/package.json

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

@@ -29,8 +29,8 @@
     "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",
+    "build:staging": "node scripts/build.mjs staging",
+    "build:production": "node scripts/build.mjs production",
     "preview": "wrangler dev",
     "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",

package/template/scripts/build.mjs

@@ -0,0 +1,114 @@
+/**
+ * Run a build for one environment.
+ *
+ *   node scripts/build.mjs staging
+ *   node scripts/build.mjs production
+ *
+ * `npm run build:staging` and `npm run build:production` are one-line aliases
+ * for these.
+ *
+ * ── WHY A SCRIPT AND NOT INLINE ENV IN package.json ────────────────────────
+ * ⚠ `PUBLIC_SITE_ENV=staging astro build` IS POSIX SHELL SYNTAX, AND npm ON
+ *   WINDOWS RUNS SCRIPTS THROUGH cmd.exe. There it is not an assignment, it is
+ *   a command name, and the build dies immediately with
+ *
+ *     'PUBLIC_SITE_ENV' is not recognized as an internal or external command
+ *
+ *   So the two most important commands in the kit did not work at all on a
+ *   platform the kit says it supports. Nothing caught it because every CI job
+ *   ran on ubuntu.
+ *
+ * ── AND WHY IT IS SAFER EVEN WHERE THE SHELL SYNTAX WORKS ──────────────────
+ * The production line repeated `PUBLIC_SITE_ENV=production` four times, once
+ * per command. Miss one and that step runs as `development` while the others
+ * do not: `astro check` types a different environment than the one that gets
+ * built, or `check-env` validates an environment nobody deployed.
+ *
+ * A mixed-environment build is precisely what `check-env.mjs` exists to catch,
+ * and it is the sort of thing that survives review because every line looks
+ * right on its own. Setting it once removes the class.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+
+const env = process.argv[2];
+
+if (env !== 'staging' && env !== 'production') {
+  console.error(
+    `\n${RED}✗ usage: node scripts/build.mjs <staging|production>${RESET}\n\n` +
+      '  The environment is not optional. A build that does not declare one\n' +
+      '  emits localhost canonical URLs — cleanly, and wrong.\n',
+  );
+  process.exit(1);
+}
+
+/*
+ * The site URL per environment. Read from package.json rather than restated
+ * here, so there is one place a project sets its hostnames.
+ *
+ * ⚠ Kept OUT of src/data/site.ts on purpose: astro.config.mjs needs the value
+ *   before any TypeScript is loaded, and site.ts imports `import.meta.env`.
+ */
+const SITE_URLS = {
+  staging: 'https://new.example.com',
+  production: 'https://example.com',
+};
+
+/**
+ * Run one step with the environment already set, and stop the build if it
+ * fails. `shell: true` on Windows because `npx`-style shims are .cmd files
+ * that execFile cannot resolve — the same reason the a11y scripts need it.
+ */
+function step(command, args) {
+  const run = spawnSync(command, args, {
+    stdio: 'inherit',
+    env: { ...process.env, PUBLIC_SITE_ENV: env, PUBLIC_SITE_URL: SITE_URLS[env] },
+    shell: process.platform === 'win32',
+  });
+  if (run.status !== 0) {
+    console.error(`\n${RED}✗ build failed at:${RESET} ${command} ${args.join(' ')}\n`);
+    process.exit(run.status ?? 1);
+  }
+}
+
+/* astro is a local binary; go through the package's own bin rather than a
+   global `astro`, which may not exist and would be the wrong version if it did. */
+const astro = ['node_modules/astro/astro.js'];
+const hasLocalAstro = existsSync('node_modules/astro/astro.js');
+
+const run = (args) =>
+  hasLocalAstro
+    ? step(process.execPath, [...astro, ...args])
+    : step('npx', ['--no-install', 'astro', ...args]);
+
+console.log(`${DIM}building ${env} → ${SITE_URLS[env]}${RESET}\n`);
+
+if (env === 'production') {
+  /* Refuse a production build of a template that has not been designed yet.
+     Before anything else, because it is the cheapest check and the most
+     embarrassing thing to deploy. */
+  step(process.execPath, ['scripts/tells.mjs', '--undecided-only']);
+  run(['check']);
+}
+
+run(['build']);
+
+if (env === 'staging') {
+  step(process.execPath, ['scripts/staging-headers.mjs']);
+}
+
+step(process.execPath, ['scripts/check-env.mjs']);
+
+if (env === 'production') {
+  step(process.execPath, ['scripts/check-sitemap.mjs']);
+}
+
+/* A sanity line, so the log says which environment actually ran rather than
+   which one was asked for. They are the same now; they were not always. */
+const pkg = existsSync('package.json') ? JSON.parse(readFileSync('package.json', 'utf8')) : {};
+console.log(`\n${DIM}${pkg.name ?? 'site'} built as ${env}${RESET}`);

package/template/scripts/check-sitemap.mjs

@@ -28,7 +28,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join, relative, sep } from 'node:path';
 
 const RESET = '[0m';
 const RED = '[31m';
@@ -78,7 +78,13 @@ const ROBOTS_META = /<meta[^>]+name=["']robots["'][^>]+content=["'][^"']*\bnoind
 const noindexed = walk(root)
   .filter((f) => f.endsWith('.html'))
   .filter((f) => ROBOTS_META.test(readFileSync(f, 'utf8')))
-  .map((f) => '/' + relative(root, f).replace(/index\.html$/, '').replace(/\.html$/, '/'))
+/* ⚠ SEPARATORS NORMALISED — `relative()` RETURNS BACKSLASHES ON WINDOWS.
+   A URL path is always `/`. Without this the map produced `/about\\` for
+   `about\\index.html`, which matched nothing: check-sitemap's contradiction
+   check silently passed a site that listed a noindexed URL in its sitemap, and
+   Search Console reports that as an error against the whole submission. */
+  .map((f) => '/' + relative(root, f).split(sep).join('/')
+      .replace(/index\.html$/, '').replace(/\.html$/, '/'))
   .map((p) => (p.endsWith('/') ? p : `${p}/`));
 
 const contradictions = noindexed.filter((p) => listed.has(p));

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/lib/routes.mjs

@@ -11,7 +11,7 @@
  */
 
 import { existsSync, readdirSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join, relative, sep } from 'node:path';
 
 /** Routes this build emitted, as absolute paths. 404 is excluded — it is not a route. */
 export function routesFromDist() {
@@ -26,7 +26,13 @@ export function routesFromDist() {
 
   return walk(root)
     .filter((f) => f.endsWith('.html') && !f.endsWith('404.html'))
-    .map((f) => '/' + relative(root, f).replace(/index\.html$/, '').replace(/\.html$/, '/'))
+    /* ⚠ SEPARATORS NORMALISED — `relative()` RETURNS BACKSLASHES ON WINDOWS.
+       A URL path is always `/`. Without this the map produced `/about\\` for
+       `about\\index.html`, which matched nothing: check-sitemap's contradiction
+       check silently passed a site that listed a noindexed URL in its sitemap, and
+       Search Console reports that as an error against the whole submission. */
+    .map((f) => '/' + relative(root, f).split(sep).join('/')
+          .replace(/index\.html$/, '').replace(/\.html$/, '/'))
     .map((p) => (p.endsWith('/') ? p : `${p}/`))
     .sort();
 }

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',