create-website-build-kit 0.1.7 → 0.1.9

package/package.json

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

@@ -11,6 +11,7 @@ npm run media                                # after adding or replacing any ima
 npm run build:staging && npx wrangler dev    # localhost:8788, real KV + secrets
 npm run a11y                                 # accessibility check, one URL per family
 npm run tells                                # what is undecided, and the design tells
+npm run check:copy                           # author notes that reached the rendered page
 npm run recon -- https://old-site.com        # inventory the old site BEFORE designing routes
 npm run dns -- old-site.com                  # capture the zone. MX loss kills client email
 npm run seo -- https://old-site.com          # optional: SEO baseline to diff after cutover
@@ -93,6 +94,14 @@ 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.
 
+**Notes to yourself never ship.** `check:copy` reads the text a browser would show — not the
+source, not comments, not `<script>` — and looks for the markers people actually leave: `TODO`,
+`FIXME`, `⚠ CONFIRM:`, `Lorem ipsum`, an unrendered `{{ placeholder }}`. It warns on staging and
+**refuses on production**, because a note is normal while building and unacceptable at go-live.
+One shipped as body copy on a service page — *"⚠ CONFIRM: the old site advertised classes every
+Saturday at 9am…"* — past clean types, clean axe and clean tells. **The question is usually real:
+move it to `BUILD-STATE.md`, do not just delete it.**
+
 **Evidence, not assertions.** `npm run a11y:evidence` writes a dated pack to
 `docs/a11y-evidence/` — commit it. It fills in the machine half and leaves the keyboard,
 screen-reader and forms passes **blank**, because no tool does those; a pack with them still

package/template/docs/runbook.md

@@ -287,6 +287,7 @@ degrades into. Run the script; keep the commands below for when you need to see
 | --- | --- |
 | One pageview per visit | Only visible in analytics Realtime |
 | A valid submission stores **and** emails | Sending one creates a real lead and a real notification |
+| **Data the client may not hold is dropped** | Only if `compliance.md` §10 named something — PHI, GDPR special categories, card numbers. Craft a submission containing exactly it, send it, then read the stored record back. The form not *asking* is not the control; the message box accepts anything. `verify` cannot do this: it would need the export token and the record schema |
 | The analytics container is the client's own | Fetch `gtm.js` and read it — see `analytics.md` |
 | A redirect lands on the **right** page | The script proves it resolves, not that it is correct |
 | It looks right on a phone | — |
@@ -490,16 +491,27 @@ In this order. Steps 1–3 happen days ahead, not on launch day.
 3. **Move Search Console verification to DNS TXT** if it currently relies on an HTML file, and
    confirm it still shows verified. File-based verification breaks the moment the file stops
    resolving, and losing verification loses the property's history.
-4. **Full verification matrix against staging.** Every row.
-5. **Deploy production** — `npm run deploy:production`. Read the bindings table in the output;
+4. **Name what enforces every retention period the privacy notice states.** KV is done for you —
+   `leadRetentionDays` becomes an `expirationTtl` and the store enforces it. **Anything else is
+   not.** R2 keeps uploaded files forever unless the bucket has a **lifecycle rule**, and that
+   rule lives in the Cloudflare dashboard, so nothing in the repo and no gate here can see it.
+   D1 needs a scheduled delete you wrote.
+
+   ⚠ A notice claiming a period nothing enforces is a false statement, and it fails silently:
+   clean build, clean deploy, correct-looking policy, data still there a year later. Caught on a
+   real build where résumés went to R2 while the retention value drove only the KV record and the
+   page copy. If you cannot name the mechanism, build it or change the notice —
+   `stacks.md` §6.
+5. **Full verification matrix against staging.** Every row.
+6. **Deploy production** — `npm run deploy:production`. Read the bindings table in the output;
    it is the only visible signal that the right environment was built.
-6. **Cut DNS over.** Watch, do not assume:
+7. **Cut DNS over.** Watch, do not assume:
    ```bash
    dig +short $PROD; dig +short www.$PROD
    curl -sI "https://$PROD/" | head -3
    ```
-7. **Remove the staging route** from the worker, or staging becomes an indexable duplicate.
-8. **Re-run the matrix against production**, including `robots.txt` (must now allow) and
+8. **Remove the staging route** from the worker, or staging becomes an indexable duplicate.
+9. **Re-run the matrix against production**, including `robots.txt` (must now allow) and
    `noindex` (must now be absent).
 
    ```bash
@@ -511,7 +523,7 @@ In this order. Steps 1–3 happen days ahead, not on launch day.
    `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
+10. **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.
 
@@ -526,7 +538,7 @@ In this order. Steps 1–3 happen days ahead, not on launch day.
    submission and rejects the whole batch with a 403 if it is not live yet. And it is Bing,
    Yandex, Seznam and Naver: **Google does not participate**, so this is never the reason a
    page is or is not in Google. The script prints both of those on every run.
-10. **Diff the zone against the capture.** The one step that catches a launch taking the
+11. **Diff the zone against the capture.** The one step that catches a launch taking the
     client's email with it:
 
     ```bash
@@ -536,10 +548,10 @@ In this order. Steps 1–3 happen days ahead, not on launch day.
     MX, SPF, DMARC, verification TXT and nameservers, compared against what was published
     before you touched anything. A dead site gets a phone call; dead email is silent.
 
-11. **Send one real enquiry through the live form** and confirm the client received it in the
+12. **Send one real enquiry through the live form** and confirm the client received it in the
     inbox they actually read.
-12. **Restore the DNS TTL** to something sane (3600s).
-13. **Point the uptime monitor at a real page and the form endpoint** — not just the homepage.
+13. **Restore the DNS TTL** to something sane (3600s).
+14. **Point the uptime monitor at a real page and the form endpoint** — not just the homepage.
     The endpoint is what breaks.
 
 ---

package/template/package.json

@@ -34,7 +34,8 @@
     "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:secrets": "node scripts/check-secrets.mjs",
+    "check:copy": "node scripts/check-copy.mjs"
   },
   "dependencies": {
     "@astrojs/cloudflare": "^14.1.7",

package/template/scripts/build.mjs

@@ -102,6 +102,11 @@ if (env === 'staging') {
   step(process.execPath, ['scripts/staging-headers.mjs']);
 }
 
+/* Warn on staging, refuse on production. A note in the copy is normal WHILE
+   building and unacceptable at go-live — the same split as
+   `tells --undecided-only`. */
+step(process.execPath, ['scripts/check-copy.mjs', ...(env === 'production' ? ['--strict'] : [])]);
+
 step(process.execPath, ['scripts/check-env.mjs']);
 
 if (env === 'production') {

package/template/scripts/check-copy.mjs

@@ -0,0 +1,135 @@
+/**
+ * Refuse to ship a build whose visible copy still talks to the author.
+ *
+ *   node scripts/check-copy.mjs            # warn
+ *   node scripts/check-copy.mjs --strict   # exit 1 on any marker
+ *
+ * `build:production` runs it strict; `build:staging` runs it as a warning,
+ * because a note in the copy is normal WHILE building and unacceptable at
+ * go-live. Same split as `tells --undecided-only`.
+ *
+ * ── THE FAILURE THIS EXISTS FOR ────────────────────────────────────────────
+ * A real build shipped this, on a service page, as body text a parent would
+ * read:
+ *
+ *   "⚠ CONFIRM: the old site advertised classes every Saturday at 9am. Does
+ *    this continue under the concierge model? Emitting a class time nobody is
+ *    running is a locked door."
+ *
+ * It was written inline in the content file while drafting, and every gate
+ * passed over it: `astro check` clean, axe clean, `tells` clean, links fine.
+ * Nothing in a build can tell a sentence meant for the client from a sentence
+ * meant for the reader — except a list of the markers people actually use.
+ *
+ * ⚠ THE QUESTION IS USUALLY REAL. The fix is not to delete the note, it is to
+ *   move it to `BUILD-STATE.md` where the other open questions live. A build
+ *   record is read before go-live; a paragraph on a service page is read by a
+ *   customer.
+ *
+ * ── WHY THIS LOOKS AT RENDERED TEXT, NOT THE FILE ──────────────────────────
+ * Searching source would flag every code comment that mentions TODO, and
+ * searching raw HTML would flag markers inside `<script>` and inside HTML
+ * comments — which are invisible to a reader and often deliberate. The check
+ * runs on the text a browser would show, plus JSON-LD, because a placeholder in
+ * structured data is quoted straight back by Google.
+ *
+ * `check-sitemap.mjs` carries the same lesson in the opposite direction: match
+ * the thing, not the word, or you train people to ignore the check.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+
+const strict = process.argv.includes('--strict');
+
+const root = ['dist/client', 'dist'].find((d) => existsSync(d));
+if (!root) {
+  console.error('check-copy: no dist/ — run a build first.');
+  process.exit(1);
+}
+
+/*
+ * ⚠ EVERY PATTERN HERE IS DELIBERATELY NARROW.
+ *
+ * `TODO` in caps is never ordinary prose. Lowercase "todo" is a Spanish word
+ * and an English noun. `CONFIRM` needs its colon or its warning sign, because
+ * "confirm your email address" is a real sentence a form says. Bare `TK` is
+ * excluded entirely — two capitals appear inside acronyms and product names,
+ * and a check that fires on those is a check people switch off.
+ */
+const MARKERS = [
+  { name: 'TODO', re: /\bTODO\b/ },
+  { name: 'FIXME', re: /\bFIXME\b/ },
+  { name: 'XXX', re: /\bXXX\b/ },
+  { name: 'TKTK', re: /\bTKTK\b/ },
+  { name: 'CONFIRM:', re: /(?:⚠\s*)?\bCONFIRM\s*:/ },
+  { name: 'placeholder text', re: /\bLorem ipsum\b/i },
+  { name: 'unresolved template', re: /\{\{\s*[\w.]+\s*\}\}/ },
+];
+
+const walk = (dir) =>
+  readdirSync(dir).flatMap((e) => {
+    const full = join(dir, e);
+    return statSync(full).isDirectory() ? walk(full) : [full];
+  });
+
+/** What a reader actually sees, plus structured data. Never script or comments. */
+function visibleText(html) {
+  const jsonLd = [...html.matchAll(/<script[^>]+application\/ld\+json[^>]*>([\s\S]*?)<\/script>/gi)]
+    .map((m) => m[1])
+    .join('\n');
+
+  const body = html
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<[^>]+>/g, ' ');
+
+  return `${body}\n${jsonLd}`;
+}
+
+const hits = [];
+
+for (const file of walk(root).filter((f) => f.endsWith('.html'))) {
+  const text = visibleText(readFileSync(file, 'utf8'));
+  for (const { name, re } of MARKERS) {
+    if (!re.test(text)) continue;
+    /* Show the sentence, so the reader can judge it without opening the file. */
+    const at = text.search(re);
+    const context = text
+      .slice(Math.max(0, at - 60), at + 120)
+      .replace(/\s+/g, ' ')
+      .trim();
+    hits.push({
+      route: '/' + relative(root, file).split(sep).join('/').replace(/index\.html$/, ''),
+      name,
+      context,
+    });
+  }
+}
+
+if (!hits.length) {
+  console.log(`${GREEN}✓${RESET} no author notes in the rendered copy`);
+  process.exit(0);
+}
+
+const label = strict ? `${RED}✗${RESET}` : `${YELLOW}!${RESET}`;
+console[strict ? 'error' : 'log'](
+  `\n${label} ${hits.length} author marker(s) in text a reader would see\n`,
+);
+for (const h of hits) {
+  console[strict ? 'error' : 'log'](`    ${h.route}  ${DIM}[${h.name}]${RESET}\n      …${h.context}…`);
+}
+
+console[strict ? 'error' : 'log'](
+  `\n  ${DIM}The question is usually real. Move it to BUILD-STATE.md, where the other\n` +
+    `  open questions live and someone reads it before go-live — do not just delete it.${RESET}\n`,
+);
+
+process.exit(strict ? 1 : 0);

package/template/scripts/tells.mjs

@@ -313,6 +313,56 @@ tell(
   );
 }
 
+/*
+ * Two rows adopted after running pbakaus/impeccable's detector over a real
+ * build. Both are signals `tells` did not have; both needed an exclusion its
+ * version does not have, and the exclusions are the reason they are usable.
+ */
+
+/*
+ * "bounce and overshoot easing" — a cubic-bezier whose control points leave
+ * [0,1] on the y axis overshoots the target and springs back.
+ *
+ * ⚠ NOT ALWAYS WRONG, which is why it is a tell and not an error. Overshoot is
+ *   right when the gesture itself carried momentum — a flick, a drag release.
+ *   It is wrong on a menu that faded in, where nothing threw it.
+ */
+{
+  const overshoot = [...sourceCss.matchAll(/cubic-bezier\(([^)]+)\)/g)]
+    .map((m) => m[1].split(',').map((n) => Number(n.trim())))
+    .filter((p) => p.length === 4 && p.every((n) => Number.isFinite(n)))
+    .filter(([, y1, , y2]) => y1 > 1 || y2 > 1 || y1 < 0 || y2 < 0);
+  tell(
+    'bounce or overshoot easing',
+    overshoot.length > 0,
+    `${overshoot.length} easing curve(s) overshoot. Right after a flick or a drag release, where momentum came from the gesture; dated on anything that simply appeared.`,
+  );
+}
+
+/*
+ * "a thick accent bar down one side of a card" — border-inline-start (or
+ * border-left) at 3px or more.
+ *
+ * ⚠ BLOCKQUOTES ARE EXCLUDED, AND THAT EXCLUSION IS THE WHOLE ROW. A rule
+ *   flagged `.prose blockquote { border-inline-start: 3px solid }` on a real
+ *   build — a left rule on a quotation is a typographic convention older than
+ *   the web, and reporting it would teach people to skim past the row. The
+ *   pattern actually meant is a notice or card wearing a coloured tab.
+ */
+{
+  const bars = [...sourceCss.matchAll(/([^{}]+)\{([^{}]*)\}/g)]
+    .filter(([, selector]) => !/blockquote|\bquote\b|\bcite\b/i.test(selector))
+    .filter(([, , body]) => {
+      const m = /border-(?:inline-start|left):\s*([\d.]+)px\s+solid/.exec(body);
+      return m && Number(m[1]) >= 3;
+    });
+  tell(
+    'a thick accent bar down one side',
+    bars.length > 1,
+    `${bars.length} rule(s) put a 3px+ coloured border on one edge. On a card or a notice it is one of the most recognisable generated-UI tells. Blockquotes are excluded — a rule beside a quotation is a convention, not a tell.`,
+  );
+}
+
 // "the 404, the empty state or the form's invalid state was never designed"
 tell(
   'no invalid / busy form state',

package/template/src/components/Header.astro

@@ -29,7 +29,22 @@ const isCurrent = (href: string) => (href === '/' ? path === '/' : path.startsWi
       {/* Text until there is a logo. A brand mark referenced before the file
           exists renders as a broken image on every page, which is worse than
           plain type — swap this for <img> once the artwork is in place, and
-          look at it on both a light and a dark background before shipping. */}
+          look at it on both a light and a dark background before shipping.
+
+          ⚠ SIZE IT BY HEIGHT, NOT WIDTH, AND KEEP IT UNDER --header-h.
+            `inline-size: 12rem; block-size: auto` on a wide mark computes to
+            whatever its aspect ratio says — on a real build a 520×227 logo came
+            out 87px tall in an 88px bar, so the LOGO was setting the header's
+            height instead of the token.
+
+            That is not cosmetic. FOUR offsets are computed from --header-h:
+            this header's min-block-size, `.under-header`'s reserve, and
+            scroll-padding-top / scroll-margin-top, which are what stop an
+            anchor target landing underneath the fixed nav. A header taller than
+            its token leaves all four short by the same amount, and none of them
+            errors.
+
+            `block-size: clamp(2.25rem, 3.4vw, 2.75rem); inline-size: auto` */}
       {business.name}
     </a>
 

package/template/src/components/PageHero.astro

@@ -29,7 +29,7 @@ const { title, lede, breadcrumbs, class: className = '' } = Astro.props;
 const crumbs = breadcrumbs ?? [];
 ---
 
-<section class:list={['hero', 'under-header', 'section--tight', className]}>
+<section class:list={['hero', 'under-header', className]}>
   <div class="container">
     {
       crumbs.length > 0 && (
@@ -59,6 +59,31 @@ const crumbs = breadcrumbs ?? [];
 </section>
 
 <style>
+  /*
+   * ⚠ THE RHYTHM BELONGS TO THE NEXT SECTION, NOT TO THIS ONE.
+   *
+   * This carried `.section--tight`, which is a SHORTHAND — it sets padding-block
+   * at both ends. Every page opens its following section with a rhythm class of
+   * its own, so two stacked: a measured 160px hole on the template's own
+   * /contact/, 176px on all four PageHero pages of a real build, and up to 232px
+   * where the next section is `.section` rather than `.section--tight`.
+   *
+   * Nothing could see it. Build green, types green, axe green, tells green — a
+   * hole is only visible by looking at the page.
+   *
+   * ⚠ AND THE SHORTHAND CLOBBERED THE HEADER OFFSET. `.under-header` reserves
+   *   the fixed header's height on padding-block-START, and global.css warns in
+   *   as many words that "a scoped component style would out-specify" it. A
+   *   shorthand from this component is exactly such a style: on a real build it
+   *   discarded the reserve and put the hero behind the nav.
+   *
+   * padding-block-END only, therefore. The offset stays with `.under-header`,
+   * the rhythm stays with whatever section comes next.
+   */
+  .hero {
+    padding-block-end: 0;
+  }
+
   .hero__crumbs ol {
     display: flex;
     flex-wrap: wrap;

package/template/src/styles/global.css

@@ -241,6 +241,16 @@ b {
  * height or the heading sits behind the nav. Applied by each opening section
  * rather than a blanket `main > :first-child` rule, which a scoped component
  * style would out-specify.
+ *
+ * ⚠ AND ONE DID. A component wrote `padding-block: <a> <b>` on the same element
+ *   — a SHORTHAND, so it set padding-block-start too, out-specified this, and
+ *   the hero sat behind the nav on a real build. On the element that carries
+ *   `.under-header`, set `padding-block-end` and never the shorthand.
+ *
+ * ⚠ NOT MOVED TO `main`, WHICH WOULD BE UN-OVERRIDABLE. The header's background
+ *   is opaque `var(--bg)`, so padding on `main` would leave a strip of body
+ *   colour behind it wherever a first section has a background of its own. The
+ *   per-section reserve is deliberate; the shorthand is the bug.
  */
 .under-header {
   padding-block-start: calc(var(--header-h) + var(--space-2xl));

package/template/src/styles/tokens.css

@@ -189,9 +189,19 @@
   --dur-slow: 420ms;
   --ease-out: cubic-bezier(0.22, 1, 0.36, 1);
   --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
-  --ease-spring: cubic-bezier(0.34, 1.4, 0.64, 1);
+  /* ⚠ NO SPRING TOKEN, DELIBERATELY. An overshoot curve is a look, and the
+     template does not ship looks — it shipped one anyway, unused, until a
+     detector found it in a client project that had inherited the dead token
+     without ever referencing it. Add one where a gesture carries real
+     momentum, and only there: a flick or a drag release. Nothing that merely
+     appeared should spring. */
 
   /* ── Chrome ────────────────────────────────────────────────────────────── */
+  /* ⚠ FOUR THINGS READ THIS: the header's min-block-size, `.under-header`'s
+     reserve, and scroll-padding-top / scroll-margin-top, which keep an anchor
+     target clear of the fixed nav. If the rendered header is taller than this
+     — a logo sized by width is the usual cause — all four are short by the same
+     amount and nothing reports it. Measure the bar, do not assume it. */
   --header-h: 4.5rem;
   --z-header: 100;
   --z-menu: 110;

package/template/wrangler.jsonc

@@ -7,6 +7,21 @@
   // the Astro adapter resolves its environment at build time and silently
   // ignores `deploy --env`, which is how a staging deploy lands on production.
   //
+  // ⚠ AND IT IGNORES `--config` THE SAME WAY, which is the next flag anyone
+  //   reaches for. @astrojs/cloudflare generates dist/server/wrangler.json —
+  //   the config actually deployed, the one carrying `main` and the real asset
+  //   directory — and builds it from the DEFAULT config path only. So
+  //   `wrangler deploy --config wrangler.production.jsonc` either fails with
+  //   "Cannot use assets with a binding in an assets-only Worker" (the
+  //   hand-written file has no `main`), or, if you work around that by
+  //   deploying the generated file instead, ships with whatever name and routes
+  //   THIS file held, whatever was built.
+  //
+  //   One config is the reason that cannot happen here. A project that grows a
+  //   second one has to rewrite dist/server/wrangler.json between build and
+  //   deploy, because there is no adapter option for it. Found on a shipped
+  //   build that needed two.
+  //
   //   npm run deploy:staging      → builds staging, deploys this worker
   //   npm run deploy:production   → builds production, deploys this worker
   //