create-website-build-kit 0.1.14 → 0.1.16

package/index.mjs

@@ -108,9 +108,41 @@ if (!existsSync(join(dest, '.gitignore'))) {
 const pkgPath = join(dest, 'package.json');
 const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
 pkg.name = name.replace(/[^a-z0-9-]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'site';
-writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 
-console.log(`  ${GREEN}✓${RESET} template → ${dir}/`);
+/*
+ * ── WHICH KIT THIS SITE CAME FROM ──────────────────────────────────────────
+ * ⚠ THE TEMPLATE IS COPIED, NOT LINKED. Nothing the kit fixes afterwards ever
+ *   reaches a site already built — not a trap, not a gate, not a pipeline
+ *   change. A shipped site sat 19% behind on every image for weeks after AVIF
+ *   landed, and it surfaced only because somebody happened to read both trees
+ *   for an unrelated reason.
+ *
+ *   Without a stamp, "is this site current?" is archaeology: compare files by
+ *   eye against a repo whose history you have to guess at. With one it is
+ *   reading a line.
+ *
+ * The VERSION, not the commit: every release is tagged, so this resolves to a
+ * commit in one lookup, and embedding a commit would mean the packer's git
+ * state deciding what ships. It goes in package.json because that is the file
+ * a developer opens first and nobody deletes.
+ */
+const kitPkg = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8'),
+);
+const stamp = { version: kitPkg.version, scaffolded: new Date().toISOString().slice(0, 10) };
+
+/* Placed straight after `version` rather than appended, so it is visible
+   without scrolling past the dependency list. */
+const ordered = {};
+for (const [key, value] of Object.entries(pkg)) {
+  ordered[key] = value;
+  if (key === 'version') ordered.websiteBuildKit = stamp;
+}
+if (!ordered.websiteBuildKit) ordered.websiteBuildKit = stamp;
+
+writeFileSync(pkgPath, `${JSON.stringify(ordered, null, 2)}\n`);
+
+console.log(`  ${GREEN}✓${RESET} template → ${dir}/${DIM}  (kit ${stamp.version})${RESET}`);
 
 const run = (cmd, args, label) => {
   const r = spawnSync(cmd, args, { cwd: dest, stdio: 'ignore', shell: process.platform === 'win32' });

package/package.json

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

@@ -95,6 +95,35 @@ The rules whose failure looks like success — double-counted pageviews, a conve
 two pipes, a trigger on `sent=1` that catches almost nothing — are in `docs/analytics.md`.
 Read it before adding any tag.
 
+**`package.json` records which kit this site came from.** `websiteBuildKit.version` is stamped at
+scaffold time and is never updated afterwards, because ⚠ **the template is copied, not linked** —
+nothing the kit fixes later reaches this site. A trap closed upstream, a gate added, a pipeline
+improved: none of it arrives. One site sat 19% behind on every image for weeks after AVIF landed.
+Compare that version against the kit's releases when something here looks older than it should.
+
+**`npm run check:drift` says what this site is behind on.** The kit is copied, not linked, so
+nothing fixed upstream arrives here. It reports and changes nothing.
+
+**Text over a photograph is measured, not forbidden.** Declare the region in
+`src/data/contrast.json` — image, box, scrim strength, text colour — and `npm run check:contrast`
+composites it and fails production below 4.5:1. ⚠ **The danger is never the photograph, it is a
+weakened scrim.** On a real site two of three regions could not fail at any photograph; the one
+exposure was a scrim lightened from 92% to 62% so a client's photography could show its colour.
+This check is what makes weakening one safe.
+
+⚠ **A CMS DELETES EVERY KEY ITS SCHEMA FORGOT.** It rewrites the whole file from the schema, so
+anything undeclared is absent from what it writes back — the client changes one field, saves, and
+the rest is gone, looking like an ordinary content commit. `npm run check:cms` refuses a
+`.pages.yml` that does not declare every key in the files it edits. **Declare keys the client will
+never touch**, or move them out of a CMS-managed file.
+
+⚠ **UPLOADS GO TO `media/source/`, NEVER `public/img/`.** The direction is the whole bug:
+`optimize-media.mjs` **reads** `media/source/` and **writes** `public/img/`. A CMS media source
+pointed at the output produces files with no variants, no width/height and no manifest entry, so
+`<Img>` throws and the client's own edit turns the build red. `<Img>` accepts a picker path like
+`/img/photos/hero-1200.webp` and normalises it back to the key, so an image field can be a real
+picker instead of asking the client to type a manifest key from memory.
+
 ⚠ **THE HONEYPOT IS CALLED `company`.** `api/contact.ts` discards any submission that fills it in,
 silently and with a 200, so a bot learns nothing. Add a real "Company" field to that form — an
 ordinary client request — and every enquiry from a company that types its name is thrown away, with

package/template/docs/handover.md

@@ -131,6 +131,36 @@ how.
 once — the header, the footer, every button, the notification emails, and what Google reads.
 Ask for them to be changed in that one file rather than page by page, or they will drift.
 
+### Editing it yourself
+
+⚠ *Delete this whole subsection if the site has no content editor.*
+
+You sign in at ⚠ **editor URL** with your ⚠ **GitHub / provider** account. Ask ⚠ **name** to add
+anyone else who needs access.
+
+| Section | What it changes |
+| --- | --- |
+| ⚠ Site settings | ⚠ business name, contact details, the main button |
+| ⚠ Pages | ⚠ the words on Home, About, Contact |
+| ⚠ Services | ⚠ each service, its photograph and description |
+| ⚠ Blog | ⚠ posts |
+
+**A change is live a few minutes after you save.** ⚠ *Confirm the real timing before sending
+this.* To check it worked, open the page in a private window — an ordinary window may show you
+the version you had before.
+
+**Photographs.** Upload them in the ⚠ **Photographs** area, then choose one in the field on the
+page you are editing. Always fill in the short description beside the image: it is what a
+blind visitor hears and what Google reads. Describe what is in the picture, not the file name.
+
+**You cannot break the website from here.** If a change is wrong, the version before it stays
+live until the new one is ready — so a mistake means your change does not appear, not that the
+site goes down. Tell ⚠ **name** what you changed and it can be put back.
+
+**Things to leave alone.** ⚠ *List anything the editor can reach that it should not — otherwise
+delete this line.* If a screen asks for something that looks technical rather than something a
+customer would read, stop and ask.
+
 ---
 
 ## 7. Accessibility

package/template/package-lock.json

@@ -21,7 +21,8 @@
         "sharp": "^0.35.3",
         "turndown": "^7.2.4",
         "typescript": "^6.0.3",
-        "wrangler": "^4.118.0"
+        "wrangler": "^4.118.0",
+        "yaml": "^2.9.0"
       },
       "engines": {
         "node": ">=22.12.0"
@@ -1337,7 +1338,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1360,7 +1360,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1380,7 +1379,6 @@
       "version": "0.35.3",
       "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.3.tgz",
       "integrity": "sha512-lUxcqWIj2wMQ9BrwNjngcr1gWUr5xgaGThBRqPPalIC2n67Cqj1uPh8NnA/ZhAg8hUbKl+kVHKwgUIwe6ZYPrg==",
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1403,7 +1401,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1420,7 +1417,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1437,7 +1433,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1454,7 +1449,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1471,7 +1465,6 @@
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1488,7 +1481,6 @@
       "cpu": [
         "riscv64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1505,7 +1497,6 @@
       "cpu": [
         "s390x"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1522,7 +1513,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1539,7 +1529,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1556,7 +1545,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1573,7 +1561,6 @@
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1596,7 +1583,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1619,7 +1605,6 @@
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1642,7 +1627,6 @@
       "cpu": [
         "riscv64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1665,7 +1649,6 @@
       "cpu": [
         "s390x"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1688,7 +1671,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1711,7 +1693,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1734,7 +1715,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1754,7 +1734,6 @@
       "version": "0.35.3",
       "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.3.tgz",
       "integrity": "sha512-cZ0XkcYGpHZkqW6iCkqTcmUC0CD9DhD5d/qeZlZkfRBn6GnHniZXLUo5+9xw8Iv76YE6LQFN9YNBlKREcCG76w==",
-      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
       "optional": true,
       "dependencies": {
@@ -1774,7 +1753,6 @@
       "cpu": [
         "wasm32"
       ],
-      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "dependencies": {
@@ -1794,7 +1772,6 @@
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1814,7 +1791,6 @@
       "cpu": [
         "ia32"
       ],
-      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1834,7 +1810,6 @@
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later",
       "optional": true,
       "os": [

package/template/package.json

@@ -8,35 +8,38 @@
     "node": ">=22.12.0"
   },
   "scripts": {
-    "dev": "astro dev",
-    "check": "astro check",
     "a11y": "node scripts/check-a11y.mjs",
     "a11y:evidence": "node scripts/a11y-evidence.mjs",
-    "reflow": "node scripts/check-reflow.mjs",
-    "console": "node scripts/check-console.mjs",
-    "shots": "node scripts/shots.mjs",
-    "tells": "node scripts/tells.mjs",
-    "media": "node scripts/optimize-media.mjs",
+    "build": "astro build",
+    "build:production": "node scripts/build.mjs production",
+    "build:staging": "node scripts/build.mjs staging",
     "cards": "node scripts/og-cards.mjs",
-    "lastmod": "node scripts/lastmod.mjs",
-    "indexnow": "node scripts/indexnow.mjs",
-    "verify": "node scripts/verify.mjs",
+    "check": "astro check",
+    "check:cms": "node scripts/check-cms.mjs",
+    "check:contrast": "node scripts/check-contrast.mjs",
+    "check:copy": "node scripts/check-copy.mjs",
+    "check:drift": "node scripts/check-drift.mjs",
+    "check:form": "node scripts/check-form.mjs",
+    "check:secrets": "node scripts/check-secrets.mjs",
     "check:sitemap": "node scripts/check-sitemap.mjs",
-    "recon": "node scripts/recon.mjs",
-    "extract": "node scripts/extract.mjs",
+    "console": "node scripts/check-console.mjs",
+    "deploy:production": "npm run build:production && wrangler deploy && node scripts/check-secrets.mjs",
+    "deploy:staging": "npm run build:staging && wrangler deploy && node scripts/check-secrets.mjs",
+    "dev": "astro dev",
     "dns": "node scripts/dns-snapshot.mjs",
-    "seo": "npx --yes @nurkamol/seo-audit@1",
-    "redirects": "node scripts/redirects.mjs",
+    "extract": "node scripts/extract.mjs",
     "handover": "node scripts/md-to-pdf.mjs docs/handover.md docs/handover.pdf",
-    "build": "astro build",
-    "build:staging": "node scripts/build.mjs staging",
-    "build:production": "node scripts/build.mjs production",
+    "indexnow": "node scripts/indexnow.mjs",
+    "lastmod": "node scripts/lastmod.mjs",
+    "media": "node scripts/optimize-media.mjs",
     "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",
-    "check:secrets": "node scripts/check-secrets.mjs",
-    "check:copy": "node scripts/check-copy.mjs",
-    "check:form": "node scripts/check-form.mjs"
+    "recon": "node scripts/recon.mjs",
+    "redirects": "node scripts/redirects.mjs",
+    "reflow": "node scripts/check-reflow.mjs",
+    "seo": "npx --yes @nurkamol/seo-audit@1",
+    "shots": "node scripts/shots.mjs",
+    "tells": "node scripts/tells.mjs",
+    "verify": "node scripts/verify.mjs"
   },
   "dependencies": {
     "@astrojs/cloudflare": "^14.1.7",
@@ -51,6 +54,7 @@
     "sharp": "^0.35.3",
     "turndown": "^7.2.4",
     "typescript": "^6.0.3",
-    "wrangler": "^4.118.0"
+    "wrangler": "^4.118.0",
+    "yaml": "^2.9.0"
   }
 }

package/template/scripts/build.mjs

@@ -101,6 +101,12 @@ if (env === 'production') {
    environments — nobody ever meant two controls to share a name. */
 step(process.execPath, ['scripts/check-form.mjs']);
 
+/* Same reasoning, and the same timing: a CMS config that does not declare every
+   key in the file it edits will delete content the first time the client saves.
+   That is a source bug, it is invisible in a build, and it costs nothing to
+   check. A no-op on projects with no `.pages.yml`. */
+step(process.execPath, ['scripts/check-cms.mjs']);
+
 run(['build']);
 
 if (env === 'staging') {
@@ -116,6 +122,10 @@ step(process.execPath, ['scripts/check-env.mjs']);
 
 if (env === 'production') {
   step(process.execPath, ['scripts/check-sitemap.mjs']);
+  /* Production only: it measures the GENERATED images, and a staging build is
+     often run before `npm run media` has caught up. A no-op until a project
+     declares regions — the template has no design and therefore none. */
+  step(process.execPath, ['scripts/check-contrast.mjs']);
 }
 
 /* A sanity line, so the log says which environment actually ran rather than