create-website-build-kit 0.1.8 → 0.1.10

package/package.json

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

@@ -94,6 +94,12 @@ 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.
 
+⚠ **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
+a thank-you page and nothing stored. **Name the real field `companyName`** and leave the trap alone;
+`npm run check:form` fails the build if two controls share a name.
+
 **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

package/template/package.json

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

package/template/scripts/build.mjs

@@ -96,6 +96,11 @@ if (env === 'production') {
   run(['check']);
 }
 
+/* Before the build, not after: a duplicate field name is a source bug, and
+   there is no reason to spend a build discovering it. Fails in BOTH
+   environments — nobody ever meant two controls to share a name. */
+step(process.execPath, ['scripts/check-form.mjs']);
+
 run(['build']);
 
 if (env === 'staging') {

package/template/scripts/check-form.mjs

@@ -0,0 +1,126 @@
+/**
+ * Refuse a build where two form controls share a `name`.
+ *
+ *   npm run check:form
+ *
+ * Runs inside `build:staging` and `build:production`. This is a correctness
+ * bug, not a note, so it fails in both — a duplicate `name` is never something
+ * anyone meant.
+ *
+ * ── THE FAILURE THIS EXISTS FOR ────────────────────────────────────────────
+ * ⚠ THE HONEYPOT IS CALLED `company`, AND THAT IS THE FIELD A B2B SITE ADDS.
+ *
+ * `ContactForm.astro` hides a trap field named `company`, and `api/contact.ts`
+ * discards any submission that fills it in — **silently and with a 200**, so a
+ * bot learns nothing:
+ *
+ *   if (input.company) return seeOther(FORM_PAGE)   // or { ok: true }
+ *
+ * Add a real "Company" field to that form, as any business site eventually
+ * does, and every enquiry from a company that types its name is thrown away.
+ * The form returns 200, the thank-you page renders, nothing is stored, nothing
+ * is logged. It is `check-secrets` all over again — leads vanishing while the
+ * site looks like it is working — except this one arrives as an ordinary client
+ * request rather than a mistake.
+ *
+ * It has already happened on a shipped build. The fix there was to name the
+ * real field `companyName`, which is right and is what this check tells you.
+ *
+ * ── WHY THE SOURCE AND NOT dist/ ───────────────────────────────────────────
+ * The contact route is `prerender = false`, so the form is not in the build
+ * output to inspect. Reading the component catches it before a deploy rather
+ * than after, which for a lead-loss bug is the difference that matters.
+ *
+ * ── WHY NOT JUST RENAME THE HONEYPOT ───────────────────────────────────────
+ * It has to look plausible to a bot, and every plausible name — `company`,
+ * `website`, `fax`, `url` — is a field some real form wants. Moving the trap
+ * moves the landmine. A check is the answer that does not depend on guessing
+ * which name nobody will need.
+ */
+
+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 DIM = '\x1b[2m';
+
+const SRC = 'src';
+if (!existsSync(SRC)) {
+  console.error('check-form: no src/ — run from the project root.');
+  process.exit(1);
+}
+
+const walk = (dir) =>
+  readdirSync(dir).flatMap((e) => {
+    const full = join(dir, e);
+    return statSync(full).isDirectory() ? walk(full) : [full];
+  });
+
+/*
+ * A control is an input, select or textarea. `name` on anything else — a
+ * <meta>, an <a>, a slot — is not a form field and must not be counted.
+ *
+ * Only QUOTED values are captured, which is also how an expression-built name
+ * is skipped: Astro writes those unquoted — name={`f-${i}`} — so they never
+ * match, and there is nothing to compare anyway.
+ *
+ * ⚠ There was a guard here testing the captured name for `{` and `$`. It could
+ *   never fire, because a captured name is quoted by definition — and it would
+ *   have wrongly skipped a real literal like name="f-{i}". Found by mutation:
+ *   deleting it changed no test, which is what an unreachable line looks like.
+ */
+const CONTROL = /<(input|select|textarea)\b[^>]*?\bname=["']([^"']+)["'][^>]*>/gis;
+
+/** The trap is marked by its wrapper class, so it can be named in the message. */
+const isHoneypot = (html, index) => html.lastIndexOf('form__trap', index) > html.lastIndexOf('</div>', index);
+
+const problems = [];
+
+for (const file of walk(SRC).filter((f) => f.endsWith('.astro'))) {
+  const html = readFileSync(file, 'utf8');
+  if (!/<form\b/i.test(html) && !/form__trap/.test(html)) continue;
+
+  const seen = new Map();
+  for (const m of html.matchAll(CONTROL)) {
+    const name = m[2];
+    const at = seen.get(name);
+    if (at === undefined) {
+      seen.set(name, m.index);
+      continue;
+    }
+    problems.push({
+      file: relative(process.cwd(), file).split(sep).join('/'),
+      name,
+      honeypot: isHoneypot(html, at) || isHoneypot(html, m.index),
+    });
+  }
+}
+
+if (!problems.length) {
+  console.log(`${GREEN}✓${RESET} no duplicate form field names`);
+  process.exit(0);
+}
+
+console.error(`\n${RED}✗ ${problems.length} duplicate form field name(s)${RESET}\n`);
+for (const p of problems) {
+  console.error(`    ${p.file}  →  name="${p.name}"`);
+  if (p.honeypot) {
+    console.error(
+      `      ${DIM}This is the HONEYPOT name. api/contact.ts discards any submission\n` +
+        `      that fills it in, silently and with a 200 — so every enquiry from a\n` +
+        `      company that types its name would be thrown away, with a thank-you\n` +
+        `      page and nothing stored.\n\n` +
+        `      Rename the REAL field — companyName, organisation — and leave the\n` +
+        `      trap alone.${RESET}`,
+    );
+  } else {
+    console.error(
+      `      ${DIM}Two controls posting the same key: the second overwrites the first\n` +
+        `      in formData, so one of them is silently discarded.${RESET}`,
+    );
+  }
+}
+console.error('');
+process.exit(1);

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

@@ -197,6 +197,11 @@
      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
   //