create-website-build-kit 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# create-website-build-kit
+
+Scaffold a production marketing site: **Astro, static, on Cloudflare Workers** — with the
+gates, the migration playbook and the accessibility work already wired.
+
+```bash
+npm create website-build-kit@latest my-site
+```
+
+Node 22.12+. It builds green immediately, with no content, no images and no secrets.
+
+## What you get
+
+A skeleton, not a theme. It ships **no palette, no typeface and no home page** — deliberately,
+so that two sites built from it cannot look alike. What it does ship is the part that takes
+longest to get right and is easiest to get subtly wrong:
+
+- **A form endpoint** with server-side validation, a honeypot, and the lead written to
+  durable storage **before** the email provider is called — so a provider outage costs a
+  notification, never a lead. It works with JavaScript off.
+- **Environment derived from one build variable** — indexability, analytics, canonical host,
+  which store leads land in, who gets notified. Nothing toggled by hand at go-live, and a bare
+  build with no environment set is refused rather than quietly publishing `localhost`
+  canonicals.
+- **A media pipeline** — AVIF and WebP per width, a dimensions manifest so nothing shifts,
+  favicons rendered from the vector.
+- **Verification against the deployed site**, as a gate that exits non-zero: routes, a real
+  404, every redirect rule *and whether its target resolves*, security headers, the meta
+  sweep, page weight, and the form submissions the API is supposed to refuse.
+- **WCAG 2.2 AA as a build constraint** — a published accessibility statement, `pa11y-ci`
+  wired up, a reflow check at 320px and 200% text, and a dated evidence pack.
+- **A migration path**: inventory the old site, extract its content to markdown, propose a
+  redirect map, and fail the build if a URL the old site served no longer resolves.
+
+## Migrating off WordPress?
+
+```bash
+npm run recon -- https://old-site.com   # URLs, preserved paths, integrations, DNS
+npm run extract                          # captured HTML → clean markdown
+npm run redirects                        # proposes a map; never writes it for you
+```
+
+Run recon **before** you design routes. For any page builder — Elementor, Divi, WPBakery,
+Bricks — the extractable copy is the rendered HTML, never the database.
+
+## The method
+
+The template is half of it. The other half is a Claude Code skill and the written method
+behind it, including a file of failures that were **green in a build**: clean build, clean
+types, clean deploy, wrong result.
+
+**https://github.com/nurkamol/website-build-kit**
+
+MIT.

package/index.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * npm create website-build-kit@latest my-site
+ *
+ * Scaffolds the Astro + Cloudflare Workers template, then gets out of the way.
+ *
+ * ── WHAT IT REFUSES TO DO ──────────────────────────────────────────────────
+ * It will not write into a directory that already has files, and it will not
+ * proceed on a Node it knows Astro rejects. Both are failures that otherwise
+ * surface much later as something that reads like a different problem: Astro on
+ * Node 20 dies with a version notice buried in a build log, and scaffolding
+ * over an existing project is unrecoverable without git.
+ *
+ * No dependencies, deliberately. `npm create` downloads this before it can do
+ * anything, so every dependency here is latency on the first command a new user
+ * ever runs.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+const argv = process.argv.slice(2);
+const flag = (name) => argv.includes(`--${name}`);
+const target = argv.find((a) => !a.startsWith('-'));
+
+if (flag('help') || flag('h')) {
+  console.log(`
+${BOLD}create-website-build-kit${RESET}
+
+  npm create website-build-kit@latest ${DIM}<directory>${RESET}
+
+  ${DIM}--no-install${RESET}   skip npm install
+  ${DIM}--no-git${RESET}       skip git init
+  ${DIM}--force${RESET}        write into a non-empty directory
+`);
+  process.exit(0);
+}
+
+/*
+ * Astro's floor is 22.12. On anything older the build dies with a version
+ * notice inside a wall of build output, which is a confusing way to learn it —
+ * so it is checked before a single file is written.
+ */
+const MIN = [22, 12];
+const current = process.versions.node.split('.').map(Number);
+if (current[0] < MIN[0] || (current[0] === MIN[0] && current[1] < MIN[1])) {
+  console.error(
+    `\n${RED}✗${RESET} Node ${process.versions.node} is too old — Astro needs ${MIN.join('.')}+.\n` +
+      `  ${DIM}nvm install 24 && nvm use 24${RESET}\n`,
+  );
+  process.exit(1);
+}
+
+console.log(`\n${BOLD}Website Build Kit${RESET}${DIM} — Astro on Cloudflare Workers${RESET}\n`);
+
+let dir = target;
+if (!dir) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  dir = (await rl.question(`  Directory ${DIM}(my-site)${RESET}: `)).trim() || 'my-site';
+  rl.close();
+}
+
+const dest = resolve(process.cwd(), dir);
+const name = dest.split('/').pop();
+
+if (existsSync(dest) && readdirSync(dest).length && !flag('force')) {
+  console.error(
+    `\n${RED}✗${RESET} ${dir} is not empty.\n` +
+      `  ${DIM}Scaffolding over an existing project cannot be undone without git.\n` +
+      `  Pick another directory, or pass --force if you are sure.${RESET}\n`,
+  );
+  process.exit(1);
+}
+
+const src = join(dirname(fileURLToPath(import.meta.url)), 'template');
+if (!existsSync(src)) {
+  console.error(`\n${RED}✗${RESET} the template is missing from this package — please report it.\n`);
+  process.exit(1);
+}
+
+mkdirSync(dest, { recursive: true });
+cpSync(src, dest, { recursive: true });
+
+/*
+ * npm strips .gitignore from published packages, so it ships as `gitignore`.
+ * Restoring it is not cosmetic: it is what keeps .dev.vars — which holds
+ * BREVO_API_KEY and the leads export token — out of the repository.
+ */
+const shipped = join(dest, 'gitignore');
+if (existsSync(shipped)) renameSync(shipped, join(dest, '.gitignore'));
+
+if (!existsSync(join(dest, '.gitignore'))) {
+  console.error(`\n${RED}✗${RESET} no .gitignore was written. Stopping — .dev.vars would be committable.\n`);
+  process.exit(1);
+}
+
+/* The site's own name, so package.json is not "site-name" forever. */
+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}/`);
+
+const run = (cmd, args, label) => {
+  const r = spawnSync(cmd, args, { cwd: dest, stdio: 'ignore', shell: process.platform === 'win32' });
+  console.log(r.status === 0 ? `  ${GREEN}✓${RESET} ${label}` : `  ${YELLOW}!${RESET} ${label} — skipped`);
+  return r.status === 0;
+};
+
+if (!flag('no-git')) {
+  if (run('git', ['init', '-q'], 'git initialised')) {
+    run('git', ['add', '-A'], 'files staged');
+  }
+}
+
+let installed = false;
+if (!flag('no-install')) {
+  console.log(`  ${DIM}installing…${RESET}`);
+  installed = run('npm', ['install', '--silent'], 'dependencies installed');
+}
+
+console.log(`
+${BOLD}Next${RESET}
+
+  ${DIM}cd${RESET} ${dir}${installed ? '' : `\n  ${DIM}npm install${RESET}`}
+
+  ${BOLD}1.${RESET} Fill in ${BOLD}src/data/business.ts${RESET} — everything reads from it, and the
+     defaults are deliberately neutral rather than correct.
+  ${BOLD}2.${RESET} ${DIM}npm run tells${RESET} — says what is still undecided. ${DIM}build:production${RESET}
+     refuses until the palette, the two typefaces and the home page are yours.
+  ${BOLD}3.${RESET} Migrating? ${DIM}npm run recon -- https://old-site.com${RESET} first, before you
+     design routes. Then ${DIM}npm run extract${RESET}.
+
+  ${DIM}docs/runbook.md §1 is the fill-in order. It builds green right now:${RESET}
+  ${DIM}npm run build:staging${RESET}
+
+${DIM}The method, and the traps: https://github.com/nurkamol/website-build-kit${RESET}
+`);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "create-website-build-kit",
+  "version": "0.1.0",
+  "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",
+    "cloudflare-workers",
+    "marketing-site",
+    "starter",
+    "template",
+    "wordpress-migration",
+    "scaffold",
+    "create",
+    "accessibility",
+    "wcag",
+    "seo"
+  ],
+  "homepage": "https://github.com/nurkamol/website-build-kit#readme",
+  "bugs": "https://github.com/nurkamol/website-build-kit/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nurkamol/website-build-kit.git",
+    "directory": "create"
+  },
+  "license": "MIT",
+  "author": "Nurkamol Vakhidov",
+  "type": "module",
+  "bin": {
+    "create-website-build-kit": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "template"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "prepack": "node prepack.mjs",
+    "postpack": "node -e \"require('fs').rmSync('template',{recursive:true,force:true})\""
+  }
+}

package/template/.dev.vars.example

@@ -0,0 +1,3 @@
+# Copy to .dev.vars for local `wrangler dev`. Never commit the real values.
+BREVO_API_KEY="xkeysib-..."
+LEADS_EXPORT_TOKEN="a long random string"

package/template/.github/workflows/gates.yml

@@ -0,0 +1,58 @@
+# Runs the gates that do not need a deployed site.
+#
+# This does NOT deploy. Cloudflare Workers Builds does that, running
+# `npm run build:production`, which carries its own gates — tells, astro check,
+# check-env and check-sitemap. This workflow exists so those same failures show
+# up on a pull request instead of at deploy time, and so `build:staging` is
+# proven from a clean checkout on every push.
+#
+# The gates that need a live URL — npm run verify, a11y, reflow — are not here.
+# They run against a deployed site, which this workflow does not have. See
+# docs/runbook.md §2.
+
+name: Gates
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # node-version-file, not a literal. A version pinned in two places drifts,
+      # and the failure is a build that works locally and not in CI.
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+          cache: npm
+
+      # `npm ci` not `npm install` — it installs exactly the lockfile and fails
+      # if package.json and the lock disagree, which is the point of running it
+      # here rather than trusting a local install.
+      - run: npm ci
+
+      # The kit's promise: green from a clean checkout, with no content, no
+      # images and no secrets. CI=true so Astro reports as a CI environment.
+      - name: Build (staging)
+        run: CI=true npm run build:staging
+
+      - name: Types
+        run: PUBLIC_SITE_ENV=staging npm run check
+
+      # Reports what is undecided and counts the design tells. Not a hard gate
+      # on a fresh template by design — `--undecided-only` blocks the
+      # HALF-decided state, which is the one that looks finished and is not.
+      - name: Design tells
+        run: npm run tells
+
+      # A no-op on staging, which emits no sitemap. Here so the check runs on
+      # every push rather than only inside build:production.
+      - name: Sitemap and noindex agree
+        run: npm run check:sitemap

package/template/.node-version

@@ -0,0 +1 @@
+24.2.0

package/template/.pa11yci.json

@@ -0,0 +1,24 @@
+{
+  "defaults": {
+    "standard": "WCAG2AA",
+    "runners": ["axe", "htmlcs"],
+    "timeout": 30000,
+    "concurrency": 4,
+    "hideElements": "iframe[src*='google.com/maps'], iframe[src*='youtube.com']",
+    "chromeLaunchConfig": { "args": ["--no-sandbox"] }
+  },
+  "//": [
+    "One URL per template family, not every page — a homepage-only pass misses",
+    "everything the blog does differently. Point these at `wrangler dev`",
+    "(localhost:8788) while building, or at the deployed staging host.",
+    "Staging emits no sitemap on purpose, which is why these are explicit.",
+    "Against production you can instead run:",
+    "  npx pa11y-ci --sitemap https://example.com/sitemap-index.xml --standard WCAG2AA"
+  ],
+  "urls": [
+    "http://localhost:8788/",
+    "http://localhost:8788/contact/",
+    "http://localhost:8788/accessibility/",
+    "http://localhost:8788/404"
+  ]
+}

package/template/BUILD-STATE.md

@@ -0,0 +1,47 @@
+# Build state
+
+⚠ **Written at every gate, not continuously.** A file edited every few minutes is noise and
+nobody reads it. Update it when a phase gate passes — `build.md` §3.
+
+**Delete this file at handover**, folding what survived into `docs/handover.md`. It is a
+working file, not a deliverable: its **Integrations** and **Preserve** lines are the source for
+`handover.md` §3 and the "deliberately not built" list in `handover.md` §4.
+
+```
+## Phase 0 · Recon          [in progress]
+
+Gates passed   —
+Locked         —
+Archetype      ⚠ from the win, not the industry — archetypes.md
+Open           ! ⚠ blocking items go here, with a date
+               ? ⚠ open questions
+Next           ⚠ one line
+```
+
+## Integrations
+
+⚠ One line each, from `recon/integrations.md`. **Every line ends in a verified state or an
+explicit dated drop. No third state** — "integrations" as one task is the item that silently
+ships at 80%, and a missing conversion tag is invisible for a month.
+
+```
+- [ ] ⚠ GA4 · G-XXXXXXXXXX · not ported · ⚠ confirm the client owns this account
+- [ ] ⚠ vendor · detected in markup · not ported · ⚠ owner unknown
+```
+
+## Preserve
+
+⚠ Paths other systems point at, from `recon/preserved.md`. Losing one is silent — see
+`stacks.md` §1d.
+
+```
+- [ ] ⚠ /sitemap_index.xml → emitted at the old path, or 301 to the new one
+- [ ] ⚠ verification file or DNS TXT carried over
+- [ ] ⚠ /feed/ → the new feed path, never dropped
+```
+
+## Decisions locked
+
+⚠ `Locked` means settled — do not reopen without saying so. This is the row that stops a pivot
+quietly becoming a rewrite. Stack, providers, archetype, and the design direction chosen from a
+real comp on staging (`design.md` §1).

package/template/CLAUDE.md

@@ -0,0 +1,153 @@
+# Working on this site
+
+Astro (static) on Cloudflare Workers. Built from
+[website-build-kit](https://github.com/nurkamol/website-build-kit).
+
+## Commands
+
+```bash
+npm run dev                                  # localhost:4321 — no bindings, /api/* will not work
+npm run media                                # after adding or replacing any image
+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 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
+npm run verify -- https://new.example.com    # the deployed site, not the build. exits non-zero
+npm run console                              # console errors + failed requests, in a real browser
+npm run shots -- --before https://old-site.com  # visual record, WHILE the old site is still up
+npm run extract                              # captured HTML → recon/extracted/*.md
+npm run deploy:staging                       # or deploy:production
+```
+
+Node **22.12+**. `.node-version` pins the version this was built against.
+
+**Use `wrangler dev` for anything touching `/api/*`, redirects, or 404 status codes.** The
+Astro dev server models none of them, and they are exactly where things break.
+
+## Rules for this codebase
+
+**`src/data/business.ts` is the only place business facts live.** Name, phone, address,
+hours, service areas, credentials — plus `locale`, `timeZone` and `schemaTypes`, whose
+defaults are deliberately neutral (`en`, `UTC`, `LocalBusiness`) rather than correct. Neutral
+is a prompt to set them; a plausible wrong value is not. The header, footer, every call-to-action, the notification
+emails and the JSON-LD all read from it. Never hard-code a phone number in a component.
+
+**`src/styles/tokens.css` is the only place a raw colour, size, radius or duration is
+written.** Components reference tokens and nothing else. If you are typing a hex or a px in a
+component, add a token instead.
+
+**This template has no design, and adding one to it is not the job.** It ships a grey
+placeholder ramp, the system stack for both faces and a scaffold home page — deliberately, so
+that two sites built from it cannot look alike. Decide the palette, the two typefaces and the
+page shapes *for this project*, in this project. Do not add a card style, a hero treatment or
+a component library to the shared layer; `global.css` carries the interactive **states**, not
+a look. Run `npm run tells` before showing anyone a page.
+
+**Legal pages are markdown, never `.astro` files.** `src/content/legal/<slug>.md` is served at
+`/<slug>/` by one route and linked in the footer from the collection itself, so the link cannot
+exist without the page. Do not write `privacy.astro`. The root-level `[slug].astro` refuses to
+build if a legal slug shadows a real page — Astro would give the page precedence and the legal
+one would be built, linked and unreachable.
+
+**`src/data/nav.ts` is the only place routes and the primary call to action live.** The
+header, the mobile menu, the footer columns and the 404's onward links all read it, so the
+404 can never offer a page that no longer exists.
+
+**Every non-production build shows a badge**, driven by `site.indexable` — it cannot be left
+on in production and cannot be turned on by hand. It reads the live DOM rather than printing
+the build variable, so it alarms when the page disagrees with the environment (`NOT NOINDEX`,
+`ANALYTICS LIVE`). `?nobadge=1` hides it for a session; never make that persistent.
+
+**`src/data/site.ts` is the only environment switch.** `PUBLIC_SITE_ENV` derives
+indexability, analytics, canonical host, which KV namespace leads land in, and who gets
+notified. Do not add a second flag — extend this one.
+
+**Images are AVIF + WebP.** `optimize-media.mjs` emits both per width and `<Img />` renders a
+`<picture>`; AVIF is 26% smaller at better quality (measured — see `stacks.md` §3). WebP is the
+fallback and is never dropped. Turning it off is `FORMATS = ['webp']` and nothing else. Note
+that a `.parent > img` selector stops matching once there is a `<picture>` — see `docs/traps.md`.
+
+**Images go through the manifest.** Put the original in `media/source/`, run `npm run media`,
+reference it by key (`photos/hero-home`) via `<Img />`. Never an external URL, never a raw
+path. This is what keeps `width`/`height` on every image so nothing shifts.
+
+**Forms write to storage before calling anyone.** In `src/pages/api/contact.ts` the KV write
+happens *before* the email provider. A provider outage should cost a notification, not a
+lead. Keep that ordering. The cross-origin refusal runs *before* validation, for the same
+reason: ordered after, it only ever fires on submissions that were being rejected anyway.
+
+**Stored leads expire.** `site.leadRetentionDays` becomes a KV `expirationTtl`, because KV
+keeps a value forever otherwise and "indefinitely" is not a retention period any regulator
+accepts. Keep the number and the privacy notice in step, and keep personal data out of KV
+metadata — `list()` returns metadata without reading values.
+
+**Everything works without JavaScript.** The page renders, the form submits, stores and
+notifies. Anything that hides an element must be the same thing that reveals it — CSS that JS
+is expected to undo shows a blank page whenever a bundle fails.
+
+**Analytics IDs are the client's own, or empty.** `src/data/site.ts` emits no tag unless both
+are set, so an unset ID cannot fall back to another project's container. Never copy one in.
+The rules whose failure looks like success — double-counted pageviews, a conversion sent down
+two pipes, a trigger on `sent=1` that catches almost nothing — are in `docs/analytics.md`.
+Read it before adding any tag.
+
+**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
+blank is an incomplete pack, not a passing one. It also warns when `/accessibility` claims a
+review date older than the run.
+
+**`/accessibility` is a published artefact, not filler.** Required under the EAA and PSBAR,
+footer-linked from every page. Keep its dates current and its known-gaps list honest — a
+documented gap is worth more than a clean claim. Never write "fully compliant".
+
+**Astro scoped styles do not reach a class passed *into* a component.** If you write
+`<Icon class="thing" />` and then `.thing { … }` in the same file, it will not match. Use
+`:global()`. This has caused real bugs; see `docs/traps.md`.
+
+## Before debugging anything strange
+
+Read **`docs/traps.md`**. Every entry failed silently — clean build, clean deploy, wrong
+result. The recurring ones:
+
+- Scoped styles not reaching a class passed into a component
+- Handlers bound behind a `transition:persist` guard holding stale, replaced elements
+- `justify-content: center` making overflowing content unreachable — use `margin: auto`
+- `100vh` being taller than the visible area on mobile — use `100dvh`
+- DNS negative caching: if `dig` and `getaddrinfo` disagree, it is your cache
+
+## Verifying
+
+Against the **deployed** site, not the build. A green build proves the bundler ran.
+
+The checklist is in `docs/runbook.md`: every route 200, unknown paths a real 404, legacy URLs
+301 to their specific equivalent, preserved paths still resolving, staging noindex with zero
+analytics references, form valid/empty/honeypot/cross-origin, and a submission producing both a
+stored record and a delivered email. It also carries the **go-live order** and the first-week
+watch list.
+
+## Handover
+
+`docs/handover.md` is the only doc written for the **client**, not a developer. Fill in every
+⚠ and render with `npm run handover`. Its "what we deliberately did not build" section is not
+optional — the difference between a decision and an oversight is whether it was written down.
+
+## Content
+
+Editing guide in `docs/content.md`. In short: posts are markdown in `src/content/blog/` with
+typed frontmatter — a bad edit fails the build rather than the page.
+
+## Do not
+
+- Hard-code a colour, size, phone number or business fact in a component — including inside a
+  JavaScript error string, which is where one hides longest
+- Ship with `--unset` still in `tokens.css`, or the scaffold home page still in place
+- Add a card, hero or section style to `global.css` — it belongs to this project, not the kit
+- Add a second environment flag
+- Reference an image by URL instead of manifest key
+- Call a third-party API before writing the submission down
+- Describe unverified work as done — check it against the deployed site
+- Copy an analytics ID from another project
+- Claim the site is "fully accessible" or "fully compliant"