create-website-build-kit 0.1.0

package/template/astro.config.mjs

@@ -0,0 +1,150 @@
+// @ts-check
+import { defineConfig, sessionDrivers } from 'astro/config';
+import cloudflare from '@astrojs/cloudflare';
+import sitemap from '@astrojs/sitemap';
+import { satteri } from '@astrojs/markdown-satteri';
+import { hastMedia } from './src/lib/hast-media.mjs';
+import { lastmodByRoute } from './src/lib/lastmod.mjs';
+import { noindexLegalRoutes } from './src/lib/legal-routes.mjs';
+
+// The build environment is the single source of truth for what this deploy
+// *is*. Nothing downstream re-derives it, and nothing is toggled by hand.
+const SITE_ENV = process.env.PUBLIC_SITE_ENV ?? 'development';
+
+/*
+ * Refuse to BUILD for a deploy without saying which deploy it is.
+ *
+ * `development` resolves the site URL to http://localhost:4321, so a build with
+ * no environment emits canonical tags pointing at localhost. It builds clean,
+ * deploys clean, and is wrong.
+ *
+ * ── WHY THIS KEYS ON THE COMMAND AND NOT ON `CI` ───────────────────────────
+ * It used to be `if (process.env.CI && …)`, which left the hole wide open on
+ * the machine where it is most likely to be walked into. `npm run build` is the
+ * most reflexive command in the npm ecosystem, and here it produced a
+ * development build in silence — verified: canonical `http://localhost:4321/`,
+ * exit 0, no warning. `npx astro build` did the same. The kit's own README
+ * claimed this was already guarded.
+ *
+ * Keying on the argv command closes both, and leaves `astro dev` alone, where
+ * `development` is the correct answer rather than a missing one.
+ */
+const isBuilding = process.argv.some((a) => a === 'build');
+
+if (isBuilding && SITE_ENV === 'development') {
+  throw new Error(
+    'PUBLIC_SITE_ENV is not set.\n\n' +
+      'A build must declare its environment, or it emits localhost canonical\n' +
+      'URLs — cleanly, with no error, and wrong. Use one of:\n\n' +
+      '  npm run build:staging      → new.example.com, noindex\n' +
+      '  npm run build:production   → example.com, indexable\n\n' +
+      'On Cloudflare Workers Builds, that is the build command in the dashboard.\n' +
+      'For a one-off local build, set it inline:\n\n' +
+      '  PUBLIC_SITE_ENV=staging npx astro build\n',
+  );
+}
+const SITE_URL =
+  process.env.PUBLIC_SITE_URL ??
+  (SITE_ENV === 'production'
+    ? 'https://example.com'
+    : SITE_ENV === 'staging'
+      ? 'https://new.example.com'
+      : 'http://localhost:4321');
+
+const isProduction = SITE_ENV === 'production';
+
+/*
+ * Per-page `lastmod` for the sitemap, from src/data/lastmod.json.
+ *
+ * Generated by `npm run lastmod` and COMMITTED — never read from git at build
+ * time. CI shallow-clones, so `git log` there returns one grafted commit for
+ * every file and every page would claim the same date. An empty map means no
+ * `lastmod` is emitted at all, which is the correct outcome: a sitemap saying
+ * "I don't know" is honest, one claiming every page changed today is not, and
+ * Google discounts a file whose dates are not consistently accurate.
+ */
+const LASTMOD = lastmodByRoute();
+
+/** Legal pages that must exist and must not be indexed. See legal-routes.mjs. */
+const NOINDEX_LEGAL = noindexLegalRoutes();
+
+export default defineConfig({
+  site: SITE_URL,
+  output: 'static',
+
+  /*
+   * This site has no sessions. Left unset, the Cloudflare adapter helpfully
+   * configures a KV session driver and writes a `SESSION` kv_namespace binding
+   * with NO id into the generated wrangler.json — which wrangler then *creates*
+   * on deploy. That works exactly once: the namespace outlives the worker, so
+   * tearing the deployment down and recreating it from git fails on a name the
+   * previous incarnation left behind. The null driver keeps the binding out.
+   */
+  // @ts-ignore - `null` exists at runtime (verified: `'null' in sessionDrivers`)
+  // but is missing from Astro's exported driver types. Not @ts-expect-error:
+  // when upstream adds it, expect-error would start failing every build.
+  session: { driver: sessionDrivers.null() },
+
+  /*
+   * `platformProxy` is NOT set here. It was, for two projects, and the
+   * Cloudflare adapter stopped accepting it — `Options` now derives from
+   * auxiliaryWorkers | configPath | inspectorPort | persistState |
+   * remoteBindings. An unknown key in an options object is dropped in silence,
+   * so it read as configuration for a build that had never once applied it.
+   *
+   * Nothing was lost: it existed to give `astro dev` real bindings, and the
+   * answer to that is `wrangler dev`, which is what the runbook already says.
+   */
+  adapter: cloudflare({
+    imageService: 'passthrough',
+  }),
+  trailingSlash: 'always',
+  build: { format: 'directory' },
+  prefetch: { prefetchAll: true, defaultStrategy: 'hover' },
+  integrations: [
+    // Staging must never advertise itself. No sitemap at all off production.
+    ...(isProduction
+      ? [
+          sitemap({
+            /*
+             * ⚠ EVERY PAGE THAT CARRIES `noindex` MUST BE EXCLUDED HERE.
+             *
+             * A URL in the sitemap is a request to index it; the same URL
+             * serving `noindex` is a refusal. Search Console reports the pair
+             * as "Submitted URL marked 'noindex'" — an ERROR, not a warning,
+             * counted against the whole submission.
+             *
+             * Seen on a live site: a /search/ page was in the sitemap and
+             * noindex from the day it was built. Nothing compares the two
+             * lists, so it stayed invisible until the sitemap was submitted.
+             *
+             * Keep this list and the pages' own `noindex` in step. The 404 is
+             * never emitted here. Add a page to BOTH or to NEITHER.
+             */
+            filter: (page) =>
+              !page.includes('/thank-you') &&
+              !page.includes('/search') &&
+              /* Legal pages carry their own `noindex`, and unlike a rendered
+                 page it is readable here — so this half derives instead of
+                 being a second list to keep in step. */
+              !NOINDEX_LEGAL.some((route) => new URL(page).pathname === route),
+            serialize(item) {
+              if (item.url === `${SITE_URL}/`) item.priority = 1.0;
+              const lastmod = LASTMOD.get(new URL(item.url).pathname);
+              if (lastmod) item.lastmod = lastmod;
+              return item;
+            },
+          }),
+        ]
+      : []),
+  ],
+  markdown: {
+    // Markdown images ship as root-relative paths the dev server can serve
+    // directly; this plugin adds srcset and intrinsic dimensions at build time.
+    processor: satteri({ hastPlugins: [hastMedia] }),
+    shikiConfig: { theme: 'github-dark' },
+  },
+  vite: {
+    build: { cssMinify: 'lightningcss' },
+  },
+});

package/template/docs/analytics.md

@@ -0,0 +1,86 @@
+# Analytics
+
+What is already measured, what is genuinely missing, and the rules whose failure
+looks like success.
+
+All IDs live in `src/data/site.ts`. They are **the client's own or empty** — an unset ID must
+never fall back to another project's container. Nothing is emitted off production, so staging
+HTML contains zero references rather than a disabled snippet.
+
+---
+
+## 1. What is already captured — do not rebuild it
+
+GA4's **enhanced measurement** is on by default and covers more than people expect. Building
+a custom event for any of these produces two numbers that disagree:
+
+| Already captured | Event |
+| --- | --- |
+| Outbound link clicks | `click` (with `outbound: true`) |
+| Site search | `view_search_results` |
+| Scroll depth (90%) | `scroll` |
+| File downloads (pdf, doc, xlsx, zip…) | `file_download` |
+| Video engagement (embedded YouTube) | `video_start`, `video_progress`, `video_complete` |
+| Page views, including history-API routes | `page_view` |
+
+Check Admin → Data streams → the stream → Enhanced measurement before writing any tag.
+
+## 2. What is genuinely missing
+
+**`tel:` and `mailto:` clicks are not captured.** They are not outbound links in GA4's sense
+and no enhanced-measurement category covers them. For a business whose phone number sits in
+every header and footer, that is a primary conversion going unmeasured.
+
+If you add it, the announcer belongs next to the one in `ContactForm.astro` — one function,
+both pipes — and the same no-double-count rule applies.
+
+## 3. The rules whose failure looks like success
+
+**Never add a GA4 configuration tag inside Tag Manager alongside a direct `gtag.js`.**
+Both fire `page_view`. Sessions halve, bounce rate collapses, and the numbers look *better*,
+which is why it survives review. `Base.astro` loads `gtag.js` directly and GTM as a
+container — do not add a GA4 Configuration tag inside the container.
+
+**Never send the same conversion down both pipes.** `announceLead()` in `ContactForm.astro`
+pushes to `dataLayer` *and* calls `gtag`. If the container also has a trigger creating a GA4
+event from `lead_submitted`, every lead counts twice.
+
+**Never trigger a conversion on "URL contains `sent=1`".** It is the obvious implementation
+and it is wrong: the enhanced path intercepts the submit and never changes the URL, so the
+trigger only catches visitors without JavaScript. It fires correctly when you test by hand and
+then under-reports for the life of the site. See the long comment in `ContactForm.astro`.
+
+**Verify the container is the client's own.** Fetch it and read it — do not reason about it:
+
+```bash
+curl -s https://example.com/ | grep -o 'GTM-[A-Z0-9]*' | sort -u
+curl -s "https://www.googletagmanager.com/gtm.js?id=GTM-XXXX" | grep -oE 'G-[A-Z0-9]{8,}' | sort -u
+```
+
+A site shipped once with a container inherited from the *previous* site's Google account:
+invisible, un-editable and un-revokable by the client, executing on every page. It was empty.
+Reading it is what found it.
+
+**Confirm one pageview per visit in Realtime.** Nothing in a build catches a double-count.
+
+## 4. Cloudflare Web Analytics
+
+Set `CF_BEACON_TOKEN` in `src/data/site.ts`. Independent of the Google tags — set either,
+both or neither. Worth having on every site:
+
+- **Real-user Core Web Vitals from the first visitor.** CrUX needs months of traffic before it
+  reports on a new domain, so field data is otherwise unavailable for exactly the period after
+  launch when it matters.
+- **A control group for ad blockers.** Cookieless and first-party, so the gap between it and
+  GA4 measures what the Google tags are losing instead of leaving you to guess.
+
+Cookieless also means it raises no consent-banner obligation of its own — see `compliance.md`
+before assuming the same of anything else.
+
+## 5. Before go-live
+
+- [ ] Both IDs are the client's own, from their own property
+- [ ] No GA4 Configuration tag inside the GTM container
+- [ ] No conversion trigger on `sent=1`
+- [ ] One submission produces exactly one `generate_lead` in Realtime
+- [ ] Staging HTML contains zero analytics references (`curl -s https://new.example.com/ | grep -c gtag` → 0)

package/template/docs/content.md

@@ -0,0 +1,138 @@
+# Editing content
+
+Everything here is a file in the repo. A bad edit **fails the build** rather than the page —
+that is deliberate, and it means a broken page can never reach visitors.
+
+---
+
+## Where things live
+
+| Change | File |
+| --- | --- |
+| Phone, address, hours, service areas, credentials | `src/data/business.ts` |
+| What you sell | `src/data/services.ts` |
+| Service-area pages | `src/data/areas.ts` |
+| Blog categories | `src/data/categories.ts` |
+| A blog post | `src/content/blog/<slug>.md` |
+| Privacy, terms, house rules | `src/content/legal/<slug>.md` |
+| Images | `media/source/…`, then `npm run media` |
+| Colours, fonts, spacing | `src/styles/tokens.css` |
+
+**`business.ts` is the single source.** The header, footer, every call to action, the
+notification emails and the structured data all read from it. Change the phone number there and
+it changes everywhere — including what Google reads. Never type a phone number into a page.
+
+**Legal pages write themselves into the footer.** A file at
+`src/content/legal/privacy.md` is served at `/privacy/` and linked in the footer automatically —
+add the file and the link appears; delete it and the link goes. There is no list to keep in
+step, which is the point: a footer link to a page nobody wrote yet is a 404 on *every* page of
+the site and nothing reports it.
+
+Each one needs `title`, `description` and `effective` (the date the terms took effect, as
+`YYYY-MM-DD`). Add `updated` only when it has genuinely changed, `navLabel` when the title is
+too long for a footer, and `order` to move it in the row. Changing an effective date is editing
+one line of frontmatter — no developer.
+
+---
+
+## Writing a post
+
+Create `src/content/blog/my-post.md`. The filename is the URL.
+
+```markdown
+---
+title: 'What a pre-purchase survey actually covers'
+description: 'One sentence that would make sense as a search result. ~155 characters.'
+pubDate: 2026-08-02
+category: 'Tips'
+image: 'blog/example-post'          # a manifest key, never a URL or a path
+imageAlt: 'A surveyor recording a reading'
+draft: false
+---
+
+Body in markdown. Start with the answer, then explain it.
+
+## Real headings, in order
+
+Never skip a level to get a size — heading level is structure, size is a token. `h4` because
+it "looked right" breaks the document outline for anyone using a screen reader.
+```
+
+**The frontmatter is typed and validated at build time** (`src/content.config.ts`). A missing
+`title`, a malformed date or a category that does not exist in `categories.ts` fails the build
+with the file and field named. That is the system working.
+
+- `draft: true` keeps it out of production entirely
+- `category` must match a `name` in `categories.ts` exactly
+- `image` is a manifest key — see below
+
+---
+
+## Images
+
+```bash
+cp ~/Desktop/new-photo.jpg media/source/blog/example-post.jpg
+npm run media
+```
+
+Then reference the **key**, not a path: `image: 'blog/example-post'`.
+
+The pipeline emits a modern format at several widths, plus a JPEG social twin for anything used
+as an `og:image`, plus a dimensions manifest so every `<img>` carries `width` and `height` and
+nothing shifts as the page loads.
+
+- **Never reference an external URL.** Hotlinked stock images rot — two Pexels URLs referenced
+  by articles had already 404'd at source on the last migration
+- **Brand assets copy byte-for-byte.** Do not run logos through the photo pipeline
+- **Cap source images at ~2400px.** True camera originals belong outside version control
+- **Write real alt text**, or `alt=""` if the image is decorative. An empty alt is correct far
+  more often than people expect; a filename never is
+- **Check for duplicate covers.** Ten of seventeen posts sharing one photo reads as a broken
+  page, and nobody notices while writing
+
+---
+
+## Adding a service or a service area
+
+Both are template + data: add an entry, the page generates.
+
+**A service area is different.** Only add a place you can describe **distinctly** — which
+authority issues the permit, what the housing stock is, what actually drives demand there.
+Pages differing by nothing but the town name are doorway pages and can be penalised. A place
+you cannot write about distinctly still belongs in `business.serviceAreas`; it just does not
+get a page.
+
+---
+
+## Accessibility, when writing
+
+The build cannot check these. They are the ones that matter and the ones that slip.
+
+- **Headings in order.** Structure, not size
+- **Link text that makes sense alone.** "Read more" is meaningless in a screen reader's link
+  list; "read the compliance guide" is not
+- **Alt text that says what the image conveys**, not what it depicts. If it conveys nothing,
+  `alt=""`
+- **Do not describe by position or colour.** "The button on the right", "the green box"
+- **Expand an abbreviation on first use.** Assume no prior knowledge
+- **Update `/accessibility`** — the statement is dated, and an undated statement reads as
+  abandoned. If you know of a gap, name it there. A documented gap is worth more than a clean
+  claim
+
+---
+
+## Publishing
+
+```bash
+git add . && git commit -m "Add post: what a pre-purchase survey covers"
+git push
+```
+
+Deployment is a push to the tracked branch. To preview first:
+
+```bash
+npm run build:staging && npx wrangler dev     # localhost:8788
+```
+
+If the build fails, **read the error** — it names the file and the field. It has caught a real
+mistake, not invented one.

package/template/docs/handover.md

@@ -0,0 +1,182 @@
+# Handover — Business Name
+
+⚠ **THIS IS A TEMPLATE. Fill it in and delete this block before sending.**
+>
+> This is the only document in the repo written for the **client**, not for whoever maintains
+> the code. `runbook.md`, `content.md` and `traps.md` are for a developer; this one is for the
+> person who owns the business and will be asked, in two years, who hosts their website.
+>
+> Render it with `npm run handover`, which writes `docs/handover.pdf` beside it. Send the PDF;
+> keep the markdown in the repo so the next change updates the same document instead of
+> starting a new one.
+>
+> Every ⚠ below marks something you must supply. A blank left in is worse than the section
+> being absent, because it reads as a completed answer.
+>
+> Cross-check against `BUILD-STATE.md` before deleting that file — its **Integrations** and
+> **Preserve** lines are the source for §3 and the "deliberately not built" list in §4.
+
+**Prepared:** ⚠ date · **By:** ⚠ name · **Site:** ⚠ https://example.com
+
+---
+
+## 1. What you own, and where
+
+You own all of it. Nothing here is held in anyone else's name, and you can move any of it
+without our involvement.
+
+| Thing | Where it lives | Who has admin |
+| --- | --- | --- |
+| Domain name | ⚠ registrar | ⚠ |
+| Website hosting | ⚠ Cloudflare account | ⚠ |
+| The site's code | ⚠ repository URL | ⚠ |
+| Email sending | ⚠ provider | ⚠ |
+| Analytics | ⚠ Google account | ⚠ |
+
+⚠ **Attach `recon/dns.md`** if this was a migration. It is the record of what the domain
+published before the move — the thing to compare against if mail or a verification ever stops
+working, and the thing a future supplier will ask for first.
+
+⚠ **Name a real person against each row, not a company.** "The agency" is not an answer when
+the agency has moved on. If any row is owned by someone unreachable, say so here in plain
+words — it is the single thing most likely to block an urgent change.
+
+**Your domain is the one that matters.** As long as you control the domain registration, you
+can move the site anywhere. Keep the registrar login somewhere you will still have it in five
+years, and turn on auto-renew.
+
+---
+
+## 2. What it costs to run
+
+⚠ Fill in real figures. A client who does not know the running cost assumes it is zero and is
+alarmed by the first invoice.
+
+| Service | What it does | Cost |
+| --- | --- | --- |
+| Domain renewal | Your address on the internet | ⚠ /year |
+| Hosting | Serves every page | ⚠ /month |
+| Email sending | Enquiry notifications | ⚠ /month |
+| ⚠ | ⚠ | ⚠ |
+
+**What happens if a payment fails**, in order of how bad it is:
+
+1. **Domain lapses** — the site goes dark and email may stop. Recoverable for a short grace
+   period, then someone else can buy your address. This is the one to protect.
+2. **Hosting lapses** — the site goes dark, but nothing is lost. Restored by paying.
+3. **Email sending lapses** — the site keeps working and enquiries are still *saved*, but
+   nobody gets notified. See §5: this is why they are stored before the email is sent.
+
+---
+
+## 3. What is connected
+
+⚠ One row per integration, from `recon/integrations.md` and the `Integrations` lines in
+`BUILD-STATE.md`. Include the ones you did not build, and say so.
+
+| Connected | What it does | Whose account |
+| --- | --- | --- |
+| ⚠ | ⚠ | ⚠ |
+
+⚠ **Flag anything inherited.** A tag or booking widget set up by a previous supplier, in an
+account nobody at the business can log into, keeps running and cannot be changed or switched
+off. It is better to say this now than to discover it during an urgent request.
+
+---
+
+## 4. What we deliberately did not build
+
+⚠ List it. This section matters as much as everything above.
+
+The difference between a decision and an oversight is whether it was written down. If a
+feature was discussed and dropped — for cost, for speed, because it duplicated something you
+already have — it belongs here with the reason.
+
+| Not built | Why | What to do if you want it |
+| --- | --- | --- |
+| ⚠ | ⚠ | ⚠ |
+
+---
+
+## 5. Your data, and how long it is kept
+
+**Enquiries from the website are saved before the notification email is sent.** If the email
+provider has an outage you lose a notification, never the enquiry itself.
+
+- **Where:** stored with the hosting, in your own account
+- **How long:** ⚠ days, then automatically deleted — see `leadRetentionDays` in
+  `src/data/site.ts`
+- **How to get it out:** ⚠ the export URL and where the token is kept
+
+⚠ **Keep this number and your privacy notice in step.** If the privacy notice says one
+retention period and the site enforces another, the published one is the promise you are
+judged against.
+
+If someone asks you to delete their data, they are entitled to that. ⚠ Name who does it and
+how.
+
+---
+
+## 6. Making changes
+
+| Change | Who can do it |
+| --- | --- |
+| ⚠ Text on an existing page | ⚠ |
+| ⚠ Adding a blog post | ⚠ |
+| ⚠ Prices, opening hours, phone number | ⚠ |
+| A new page or section | A developer |
+| Anything about how it looks | A developer |
+
+**Opening hours, address and phone number live in one place** and update the whole site at
+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.
+
+---
+
+## 7. Accessibility
+
+⚠ Do not describe the site as "fully accessible" or "fully compliant". Nobody can claim that
+honestly, and the claim is what gets challenged.
+
+- **Published statement:** ⚠ https://example.com/accessibility
+- **Standard targeted:** WCAG 2.2 AA
+- **Last tested:** ⚠ date · **Tested how:** ⚠ automated tool + which pages by hand
+- **Evidence:** ⚠ attach the newest pack from `docs/a11y-evidence/`
+- **Known gaps:** ⚠ list them, with who owns each
+
+**This needs re-testing whenever the site's layout changes**, not on a calendar. The published
+statement carries a date and a claim; a redesign that leaves the date alone turns it into a
+false statement about a site that no longer exists.
+
+⚠ Run `npm run a11y:evidence` after any layout change — it runs the automated sweep and the
+reflow pass, writes a dated pack, and tells you when the statement's date has fallen behind.
+Update the statement when you do.
+
+---
+
+## 8. If something looks wrong
+
+In order — the first two resolve most of it:
+
+1. **Hard-refresh the page.** Browsers hold on to old copies. `Cmd+Shift+R` or `Ctrl+F5`.
+2. **Try it on a phone and on another network.** If it works there, it is your connection or
+   your browser, not the site.
+3. **Check the enquiry form** by sending yourself one. It should arrive within a minute.
+4. ⚠ **Contact:** name, email, and what response time to expect.
+
+⚠ Tell them what is *not* an emergency. A page that looks slightly different in one browser is
+not the same as the site being down, and knowing the difference saves a weekend call.
+
+---
+
+## 9. Current state
+
+⚠ What is actually live, and what is outstanding, on the day you send this. Be specific and
+dated. This section is why the document is trusted in six months.
+
+**Live:** ⚠
+
+**Outstanding:** ⚠ with an owner and a date against each
+
+**Watch in the first month:** ⚠ e.g. enquiries arriving, search rankings settling after the
+address change, the 404 log for URLs the migration missed