create-website-build-kit 0.1.9 → 0.1.11

package/package.json

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

@@ -13,6 +13,7 @@ npm run a11y                                 # accessibility check, one URL per
 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
+#   --allow-internal                         # ...if the old site is on a VPN or a private address
 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
 npm run verify -- https://new.example.com    # the deployed site, not the build. exits non-zero
@@ -94,6 +95,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/scripts/recon.mjs

@@ -37,27 +37,156 @@ const YELLOW = '';
 const DIM = '';
 const BOLD = '';
 
+/*
+ * ── WHAT THIS BLOCKS, AND WHAT IT DOES NOT ─────────────────────────────────
+ * Loopback, the RFC1918 private ranges, link-local (which is where the cloud
+ * metadata services live, at 169.254.169.254) and localhost. The threat is a
+ * redirect: the OLD site is not ours, and a 302 it issues must not be able to
+ * steer this crawler at infrastructure on the operator's network.
+ *
+ * ⚠ THIS IS A STRING BLOCKLIST AND IT ONLY SEES LITERAL ADDRESSES. A HOSTNAME
+ *   THAT *RESOLVES* TO LOOPBACK WALKS STRAIGHT THROUGH — `localtest.me` is a
+ *   public name that resolves to ::1 today, and any attacker can point their
+ *   own name wherever they like. Closing that needs resolution before connect
+ *   plus a pinned socket, which fetch does not expose.
+ *
+ *   So treat this as defence in depth, not a barrier. It raises the cost of
+ *   the obvious attack; it does not make the crawler safe to point at a host
+ *   you do not trust.
+ *
+ * Node's URL parser canonicalises before we ever see the host, which is why
+ * the short forms need no special handling: 127.1, 2130706433 and 0177.0.0.1
+ * all arrive as 127.0.0.1, and [0:0:0:0:0:0:0:1] arrives as ::1.
+ *
+ * ⚠ IT CANONICALISES IPv4-MAPPED IPv6 THE WRONG WAY FOR US. `::ffff:127.0.0.1`
+ *   comes back as `[::ffff:7f00:1]` — the same address in hex — so a blocklist
+ *   written in dotted quad never matches it. It has to be folded back by hand,
+ *   which is what unmapV4 does. Stripping the literal `::ffff:` prefix is NOT
+ *   enough and looks like it works.
+ */
+const BLOCKED_HOST_RE =
+  /^(127(?:\.\d{1,3}){3}|10(?:\.\d{1,3}){3}|172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}|192\.168(?:\.\d{1,3}){2}|169\.254(?:\.\d{1,3}){2}|0\.0\.0\.0|localhost|::1|metadata\.google\.internal)$/i;
+
+/** `::ffff:7f00:1` → `127.0.0.1`. Returns the host unchanged if it is not mapped. */
+function unmapV4(host) {
+  const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(host);
+  if (hex) {
+    const [hi, lo] = [parseInt(hex[1], 16), parseInt(hex[2], 16)];
+    return [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff].join('.');
+  }
+  return host.replace(/^::ffff:/i, '');
+}
+
+/**
+ * Why this URL is refused, or null if it is fine. Never throws.
+ *
+ * The `kind` matters: only a `host` refusal is something --allow-internal can
+ * excuse. A bad protocol is a typo, and telling someone to pass a flag that
+ * cannot help them is worse than saying nothing.
+ */
+function blockedReason(url, { allowInternal = false } = {}) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { kind: 'url', reason: `unparseable URL: ${url}` };
+  }
+  const { protocol, hostname } = parsed;
+  if (protocol !== 'http:' && protocol !== 'https:') {
+    return { kind: 'protocol', reason: `blocked protocol: ${protocol}` };
+  }
+  if (allowInternal) return null;
+  const host = unmapV4(hostname.replace(/^\[|\]$/g, ''));
+  if (BLOCKED_HOST_RE.test(host)) return { kind: 'host', reason: `blocked internal host: ${hostname}` };
+  return null;
+}
+
 const argv = process.argv.slice(2);
 const target = argv.find((a) => !a.startsWith('--'));
 const useWayback = !argv.includes('--no-wayback');
+const allowInternal = argv.includes('--allow-internal');
 
 if (!target) {
-  console.error('usage: npm run recon -- https://old-site.com [--no-wayback]');
+  console.error('usage: npm run recon -- https://old-site.com [--no-wayback] [--allow-internal]');
   process.exit(1);
 }
 
-const ORIGIN = (target.startsWith('http') ? target : `https://${target}`).replace(/\/$/, '');
+/*
+ * ⚠ ONLY PREPEND A SCHEME WHEN THERE IS NONE. `target.startsWith('http')` was
+ *   the old test, and it turned `file:///etc/passwd` into
+ *   `https://file:///etc/passwd` — which parses, with hostname `file`, so the
+ *   protocol check below could never fire on a target the user typed.
+ */
+const hasScheme = /^[a-z][a-z0-9+.-]*:/i.test(target);
+const ORIGIN = (hasScheme ? target : `https://${target}`).replace(/\/$/, '');
 const HOST = new URL(ORIGIN).hostname;
 const OUT = 'recon';
 
+/*
+ * The target is checked too, not just the redirects. An old site behind a VPN
+ * on a private address is a real thing to recon, so this is a flag rather than
+ * a refusal — but it has to be asked for, because the default has to be the
+ * safe one and `--allow-internal` also relaxes the redirect check below.
+ */
+const originRefusal = blockedReason(ORIGIN, { allowInternal });
+if (originRefusal) {
+  const hint =
+    originRefusal.kind === 'host'
+      ? `  recon crawls the old LIVE site, so an internal address is usually a typo.\n` +
+        `  If it is not — the old site is on a VPN, or behind a private address —\n` +
+        `  pass ${BOLD}--allow-internal${RESET} and it will crawl it.\n`
+      : `  recon speaks http and https. Give it the URL you would type into a browser.\n`;
+  console.error(`\n${RED}✗ ${originRefusal.reason}${RESET}\n\n${hint}`);
+  process.exit(1);
+}
+
 const section = (t) => console.log(`\n${BOLD}── ${t} ${'─'.repeat(Math.max(0, 56 - t.length))}${RESET}`);
 const notes = [];
 
+/*
+ * ⚠ A REFUSAL IS NOT A NETWORK ERROR, AND MUST NOT LOOK LIKE ONE.
+ *
+ *   req() returns null when a fetch fails, and every caller reads that as "the
+ *   old site did not answer". If a blocked host returned null the same way, a
+ *   refused crawl would be reported as an unreachable site: recon would print a
+ *   thin inventory, exit 0, and nobody would learn that pages were skipped on
+ *   purpose. That is the exact shape of failure this kit exists to prevent, so
+ *   a refusal says so on stdout AND lands in the notes at the end of the run.
+ *
+ *   Deduplicated by reason: a site that redirects every path to the same
+ *   internal host would otherwise print one line per URL.
+ */
+const refusals = new Set();
+
+function refuse(reason, url) {
+  if (!refusals.has(reason)) {
+    refusals.add(reason);
+    console.log(`  ${YELLOW}refused${RESET} ${reason}`);
+    notes.push(
+      `Refused to fetch ${url} — ${reason}. This was NOT a network error: the crawl skipped it ` +
+        `deliberately, so the inventory is incomplete. Re-run with --allow-internal if that host is yours.`,
+    );
+  }
+  return null;
+}
+
 async function req(url, options = {}) {
+  const refusal = blockedReason(url, { allowInternal });
+  if (refusal) return refuse(refusal.reason, url);
+
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 20000);
+  const follow = options.redirect !== 'manual';
   try {
-    return await fetch(url, { redirect: 'follow', signal: controller.signal, ...options });
+    let res = await fetch(url, { ...options, redirect: 'manual', signal: controller.signal });
+    for (let hops = 0; follow && res.status >= 300 && res.status < 400 && res.headers.get('location') && hops < 5; hops++) {
+      const next = new URL(res.headers.get('location'), url).toString();
+      const hopRefusal = blockedReason(next, { allowInternal });
+      if (hopRefusal) return refuse(`${hopRefusal.reason} — reached by a redirect from ${url}`, next);
+      url = next;
+      res = await fetch(url, { ...options, redirect: 'manual', signal: controller.signal });
+    }
+    return res;
   } catch {
     return null;
   } finally {
@@ -407,7 +536,8 @@ const VENDORS = [
   'jobber', 'servicetitan', 'momence', 'wellnessliving', 'glofox', 'pike13', 'cookieyes', 'cookiebot', 'complianz', 'algolia', 'mindbody',
   'squarespace', 'wix', 'shopify', 'woocommerce', 'memberpress',
 ];
-const vendors = VENDORS.filter((v) => new RegExp(v.replace('.', '\\.'), 'i').test(corpus));
+const corpusLower = corpus.toLowerCase();
+const vendors = VENDORS.filter((v) => corpusLower.includes(v.toLowerCase()));
 
 const origins = [...new Set([...corpus.matchAll(/(?:src|href)=["']https?:\/\/([^"'/]+)/g)].map((m) => m[1]))]
   .filter((h) => !h.endsWith(HOST.replace(/^www\./, '')))