@cparkerwebm/webmonterey 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparkerwebm/webmonterey",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "The WebMonterey Astro framework: plumbing, design system, and Claude Code skills for client sites on Cloudflare Workers",
   "license": "MIT",
@@ -49,6 +49,8 @@
     "./pages/slug": "./src/pages/[...slug].astro",
     "./pages/robots": "./src/pages/robots.txt.ts",
     "./pages/webm": "./src/pages/webm.astro",
+    "./pages/webmaster": "./src/pages/webmaster.astro",
+    "./pages/webmaster-og": "./src/pages/webmaster-og.png.ts",
     "./pages/404.astro": "./src/pages/404.astro",
     "./emails": "./src/emails/index.ts",
     "./cloudflare/d1": "./src/includes/cloudflare/d1/client.ts",
@@ -64,8 +66,8 @@
     "./webmonterey/compliance/ConsentInit.astro": "./src/includes/webmonterey/compliance/ConsentInit.astro",
     "./webmonterey/forms": "./src/includes/webmonterey/forms/honeypot.ts",
     "./webmonterey/prose": "./src/includes/webmonterey/prose/inline.ts",
-    "./webmonterey/credits": "./src/includes/webmonterey/credits/credit.ts",
-    "./webmonterey/credits/Credit.astro": "./src/includes/webmonterey/credits/Credit.astro",
+    "./webmonterey/webmaster": "./src/includes/webmonterey/webmaster/webmaster.ts",
+    "./webmonterey/webmaster/Webmaster.astro": "./src/includes/webmonterey/webmaster/Webmaster.astro",
     "./webmonterey/scroll-top/ScrollTop.astro": "./src/includes/webmonterey/scroll-top/ScrollTop.astro",
     "./structured-data": "./src/includes/webmonterey/structured-data/nodes.ts",
     "./schema/design.json": "./schema/design.json",

package/skills/launch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: launch
-description: Launch a WebMonterey client site onto its real domain - structured data, Turnstile, sending domain, production secrets, remote migrations, custom domain, verification, and the environment flip. Use for "launch the site", "point the domain at it", "we're going live", "take it out of preview".
+description: Launch a WebMonterey client site onto its real domain - build audit (alt text, links, sitemap), structured data, Turnstile, sending domain, production secrets, remote migrations, custom domain, verification, analytics confirmation, and the environment flip. Use for "launch the site", "point the domain at it", "we're going live", "take it out of preview".
 ---
 
 # Launch
@@ -15,9 +15,34 @@ npx webm doctor
 npm run build
 ```
 
-Both clean. Doctor's warnings about placeholder artwork and the missing agency credit become
+Both clean. Doctor's warnings about placeholder artwork and the missing webmaster credit become
 blocking here: replace the seeded favicons and share image with the client's own, and confirm
-the footer imports `Credit.astro`.
+the footer imports `Webmaster.astro` - it links to the `/webmaster` page every site has, and
+without the credit that page is reachable from nothing.
+
+## 1b. Audit the build
+
+```sh
+npx webm audit
+```
+
+It reads `dist/client` and reports three things a person never checks exhaustively on a
+forty-page site. Fix each and rebuild until it is clean:
+
+- **Images with no `alt` attribute.** Write the alt text yourself: open the image, read the
+  copy around it, and describe what it shows in that context - not what it is ("photo"), what it
+  says. A purely decorative image gets `alt=""`, declared explicitly. The alt lives wherever the
+  `<img>` is authored: the component's markup, or the block's page JSON if the schema carries it.
+  Do not leave one for later; a missing alt on a launched site is an accessibility failure and a
+  lost image-search result.
+- **Broken internal links.** Every `href` must land on a built page or a route in
+  `run_worker_first`. A typo'd slug, a page that was renamed, a form action that moved.
+- **The sitemap.** Built, advertised in `robots.txt`, every URL on the production domain and
+  landing on a page. After launch, fetch `https://<domain>/sitemap-index.xml` in a browser and
+  submit it in Search Console.
+
+External links are probed too and reported as warnings: many sites refuse anything that is not a
+browser, so open each flagged one before calling it broken.
 
 ## 2. Structured data
 
@@ -159,10 +184,25 @@ curl -H "Sec-Fetch-Dest: document" -H "Sec-Fetch-Mode: navigate" https://<domain
 That header is what the asset router branches on. Without it curl gets the real page and Chrome
 gets the 404.
 
-**A form test before step 10 goes to `stagingEmail`** with `[staging → …]` in the subject naming
+**A form test before step 11 goes to `stagingEmail`** with `[staging → …]` in the subject naming
 who it was really for. That is the system working - check that inbox, not the client's.
 
-## 10. Hand the site its email back, and record the launch
+## 10. Analytics - two confirmations, asked out loud
+
+Neither of these can be checked from the repo, so **ask, and wait for the answer.** Do not
+proceed on an assumption, and do not mark either done because the field is filled in.
+
+1. **"Is Google Tag Manager configured for this site?"** - meaning the container exists, its
+   tags are published (not just saved), and `gtmId` in `webmonterey.json` is that container. A
+   `gtmId` with an unpublished container loads a script that fires nothing. If the site has no
+   analytics by agreement, confirm that instead and move on.
+2. **"Has the launch annotation been added in Google Analytics?"** - a dated note on the
+   property for the launch, so the traffic change that follows has an explanation next to it
+   when someone looks a year from now.
+
+Record the answers in the launch commit message.
+
+## 11. Hand the site its email back, and record the launch
 
 In one change:
 
@@ -171,13 +211,21 @@ In one change:
 "launched": "YYYY-MM-DD"
 ```
 
+**This flip is also what makes the site indexable, so it happens here and not before.** While
+`environment` says `staging`, every build is a preview - every page noindex with no canonical,
+no sitemap, robots.txt disallowing everything, no Google Tag Manager - on every hostname, `main`
+included. Flip it before the custom domain is live and the `workers.dev` copy is what gets
+indexed.
+
 Until `environment` flips, every message the site sends is redirected to `stagingEmail` - correct
 right up to the moment the domain is attached and wrong immediately after: the form keeps saying
 thank you, the client's inbox stays empty, and the first anyone hears of it is a customer asking
-why nobody called back. `webm doctor` fails a launched site still declared staging, which is why
-both fields change together.
+why nobody called back. And a launched site left on `staging` is invisible to search: every page
+noindex, no sitemap, `Disallow: /`. `webm doctor` fails a launched site still declared staging,
+which is why both fields change together.
 
-Anything served from `workers.dev` is still treated as staging whatever this says, so branch
-previews of the live site keep redirecting. That is deliberate.
+Anything served from `workers.dev` is still treated as staging for MAIL whatever this says, and
+any branch other than `main` still builds as a preview, so branch previews of the live site keep
+redirecting and stay out of the index. That is deliberate.
 
 Commit, push, and confirm the deploy. Then run `npx webm doctor` one last time: zero failures.

package/skills/start/SKILL.md

@@ -97,27 +97,81 @@ like a bot does.
 **Every route with `export const prerender = false` goes in `run_worker_first`, in both slash
 forms.** Miss one and it returns 200 to curl and a 404 page to Chrome. `webm doctor` checks.
 
-## 5. Workers Builds
+## 5. Create the Worker - once, from the laptop
 
-Connect the repo in the Cloudflare dashboard: **Workers & Pages → Create → Import a repository**.
-The Worker name must be the slug exactly as `wrangler.jsonc` has it - Workers Builds fails on a
-mismatch.
+Guarded and re-runnable: skip this step when the Worker already exists.
 
-No build variables are needed. **Push to deploy from then on** - a `wrangler deploy` from a
-laptop creates a version no build produced, so history stops describing what is live, and the
-next push reverts it.
+```sh
+npx wrangler deployments list --name <slug>   # a list: it exists. "does not exist [code: 10007]": create it
+```
+
+The name is `name` in `wrangler.jsonc`. When there is nothing:
+
+```sh
+npm run build            # a real build; `dev` proves nothing here
+npx wrangler deploy
+```
+
+**This is the ONLY laptop deploy a site ever gets.** Before Workers Builds is connected, one
+deploy is exactly how the Worker comes into existence. After it is connected (step 6) a laptop
+deploy is the mistake: a version no build produced, which the next push reverts. This skill used
+to stop here and say to create the Worker in the dashboard by hand, and on one site nobody did -
+the result was a repo, a D1 database and nothing serving. `webm doctor` now warns on that.
+
+The deploy provisions something `wrangler.jsonc` does not name, and that is expected: the Astro
+Cloudflare adapter adds a `SESSION` KV binding, which wrangler auto-provisions as
+`<slug>-session`. Do not add it to the config by hand.
+
+Then verify. Wait a minute first - a brand-new Worker can return `error code: 1042` on valid
+paths for about that long. In a real browser with the console open, load
+`https://<slug>.<account>.workers.dev`: the home page renders, the console is clean. Then check
+one on-demand route with a document-style request, if the site has one yet - a fresh scaffold's
+only Worker route is the form action, which is POST-only:
+
+```sh
+curl -sI -H 'Sec-Fetch-Dest: document' https://<slug>.<account>.workers.dev/<on-demand-route>
+```
+
+The asset router keys off that header and plain curl does not send it, so a route that is 200 to
+`curl` and 404 here is missing from `run_worker_first` (step 4).
+
+## 6. Connect the repo
 
-## 6. Verify the first deploy
+In the dashboard, on the Worker that now exists: **Settings → Builds → connect `<org>/<slug>`**,
+production branch `main`, no build variables. Connecting a repo to an EXISTING Worker is the
+smaller step - importing a repository and typing the Worker name in by hand is where the name
+mismatch Workers Builds fails on comes from.
 
-Wait a minute after the build reports success - a brand-new Worker can return `error code:
-1042` on valid paths for about that long. Then, in a real browser with the console open, load
-the `workers.dev` URL. The home page renders, the console is clean.
+**Push to deploy from then on.** The first push supersedes the laptop version. A `wrangler
+deploy` from a laptop after this point creates a version no build produced, so history stops
+describing what is live and the next push reverts it.
 
-## 7. Hand over
+Confirm it took:
+
+```sh
+npx wrangler deployments list --name <slug>
+```
+
+The newest deployment's Source is no longer `Upload`.
+
+## 7. Verify the first push
+
+Wait a minute after the build reports success - the 1042 window again - then load the
+`workers.dev` URL in a real browser with the console open. The home page renders, the console is
+clean.
+
+## 8. Hand over
 
 Workers Builds comments the preview URL on every PR - that is the client's review link. Preview
 hostnames use the slug, so Chrome's lookalike warning should not appear; if it does, it is a
 URL-shape false positive and **Ignore is safe**.
 
+A preview build is safe to hand out: every page is noindex, there is no sitemap, robots.txt
+disallows everything, analytics does not load, and mail is redirected to `stagingEmail`. The
+client can click anything. **Every build of this site is a preview while `environment` is
+`staging`** - `main` and the laptop included - so nothing is indexable before `/webm:launch`
+flips it, and that flip is what makes the site indexable. On a launched site the production
+branch is `main`; anything else previews.
+
 Next: `/webm:new-component` for each block, then `/webm:launch` when the site is
 content-complete and approved on a preview.

package/skills/traps/SKILL.md

@@ -134,6 +134,15 @@ _Worker_, not a _version_, so it can only serve production, and per-version prev
 **`workers_dev: false` does NOT disable preview URLs.** Separate switches, which is why
 wrangler.jsonc sets both explicitly.
 
+**A branch preview is a different build, on purpose.** Workers Builds injects
+`WORKERS_CI_BRANCH`; on any branch but the production one (`main`, or the integration's
+`productionBranch`) every page is noindex with no canonical, there is no sitemap, `robots.txt`
+disallows everything, GTM does not load, and the `/webmaster` page emits no graph. Email is
+already redirected by the `workers.dev` hostname. So a client's review link can neither be
+indexed nor show up in their analytics. **A local build is not a preview** - `npm run preview`
+builds production, which is what you want to inspect. To see the preview shape locally:
+`WORKERS_CI_BRANCH=x npm run build`.
+
 **`wrangler deployments list` misleads twice.** `Source: Unknown (deployment)` appears even for
 Workers Builds deployments — it describes the author, not the origin. And the list pages at 10
 entries, so "has the count gone up?" can never become a way of waiting for a deploy.
@@ -320,6 +329,14 @@ divert every enquiry the day a site answers on `www.`.
 nightly sweep — the check that reads a hostname cannot see a cron at all. This is why the switch
 is config rather than something derived from the URL.
 
+**A staging site is a preview build everywhere, and flipping `environment` is what makes it
+indexable.** On `staging` every build — a branch, `main`, a laptop — is noindex on every page with
+no canonical, no sitemap, `Disallow: /` and no Google Tag Manager. So a site that has not launched
+cannot be indexed on its `workers.dev` URL, and a launched site left on `staging` after 1.3.0
+drops out of search with no symptom on the page. `webm doctor` fails the second; `/webm:launch`
+flips the switch only once the custom domain is live. A branch other than `main` previews
+regardless of the switch.
+
 **Check the client's existing DMARC before adding a sending subdomain.** A DMARC record on
 `example.com` applies to its subdomains by default. If the client publishes `p=reject` and DKIM on
 the new subdomain is not right, **every message vanishes** — no bounce, no error, nothing in the

package/src/cli/audit.test.ts

@@ -0,0 +1,120 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { attr, audit, auditSitemap, hasAttr, imagesWithoutAlt, links, resolves } from './audit.ts';
+
+const build = (
+  files: Record<string, string>,
+  extra: Partial<Parameters<typeof audit>[0]> = {},
+) => ({
+  pages: new Map(Object.entries(files).filter(([k]) => k.endsWith('.html'))),
+  exists: (rel: string) => rel in files,
+  read: (rel: string) => files[rel] ?? null,
+  workerFirst: ['/_actions/*'],
+  origin: 'https://example.com',
+  ...extra,
+});
+
+test('attr reads quoted and bare values, and hasAttr sees a valueless attribute', () => {
+  assert.equal(attr('<img src="a.png" alt="A thing">', 'alt'), 'A thing');
+  assert.equal(attr("<img src='a.png' alt=''>", 'alt'), '');
+  assert.equal(attr('<img src=a.png>', 'src'), 'a.png');
+  assert.equal(attr('<img src="a.png">', 'alt'), null);
+  assert.equal(hasAttr('<img src="a.png" alt>', 'alt'), true);
+  assert.equal(hasAttr('<img src="a.png" data-alt="x">', 'alt'), false, 'data-alt is not alt');
+});
+
+test('an image with no alt attribute is reported; an empty alt is a decorative declaration', () => {
+  const html = `<img src="/hero.jpg"><img src="/deco.svg" alt=""><img alt="Fine" src="/ok.png"><IMG SRC="/caps.png">`;
+  assert.deepEqual(imagesWithoutAlt(html), ['/hero.jpg', '/caps.png']);
+});
+
+test('links are split into internal paths and external URLs, skipping non-navigations', () => {
+  const html = `
+    <a href="/about">a</a> <a href="/about/">b</a> <a href="mailto:x@y.z">m</a> <a href="#top">t</a>
+    <a href="https://example.com/contact">own origin</a> <a href="https://other.test/x">ext</a>
+    <a href="//cdn.test/file">proto-relative</a> <a href="tel:+1">p</a>`;
+  const { internal, external } = links(html, 'https://example.com');
+  assert.deepEqual(internal.sort(), ['/about', '/about/', '/contact']);
+  assert.deepEqual(external.sort(), ['https://cdn.test/file', 'https://other.test/x']);
+});
+
+test('an internal link resolves to a built file in any of the forms the router serves', () => {
+  const input = build({
+    'index.html': '',
+    'about/index.html': '',
+    'privacy.html': '',
+    'a.pdf': '',
+  });
+  for (const href of [
+    '/',
+    '/about',
+    '/about/',
+    '/about#team',
+    '/about?x=1',
+    '/privacy',
+    '/a.pdf',
+  ]) {
+    assert.equal(resolves(href, input), true, href);
+  }
+  assert.equal(resolves('/missing', input), false);
+});
+
+test('an on-demand route in run_worker_first is not reported as broken', () => {
+  const input = build(
+    { 'index.html': '' },
+    { workerFirst: ['/_actions/*', '/contact', '/contact/', '/app/*'] },
+  );
+  assert.equal(resolves('/contact', input), true);
+  assert.equal(resolves('/contact/', input), true);
+  assert.equal(resolves('/app/dashboard', input), true);
+  assert.equal(resolves('/app', input), true);
+  assert.equal(resolves('/elsewhere', input), false);
+});
+
+test('the sitemap must exist, be advertised, and every URL must land', () => {
+  const ok = build({
+    'index.html': '',
+    'about/index.html': '',
+    'robots.txt': 'User-agent: *\nAllow: /\n\nSitemap: https://example.com/sitemap-index.xml\n',
+    'sitemap-index.xml':
+      '<sitemapindex><sitemap><loc>https://example.com/sitemap-0.xml</loc></sitemap></sitemapindex>',
+    'sitemap-0.xml':
+      '<urlset><url><loc>https://example.com/</loc></url><url><loc>https://example.com/about/</loc></url></urlset>',
+  });
+  assert.deepEqual(auditSitemap(ok), { problems: [], urls: 2 });
+
+  const bad = build({
+    'index.html': '',
+    'robots.txt': 'User-agent: *\n',
+    'sitemap-index.xml':
+      '<sitemapindex><sitemap><loc>https://example.com/sitemap-0.xml</loc></sitemap></sitemapindex>',
+    'sitemap-0.xml':
+      '<urlset><url><loc>https://example.com/gone/</loc></url><url><loc>https://wrong.test/</loc></url></urlset>',
+  });
+  const { problems } = auditSitemap(bad);
+  assert.ok(problems.some((p) => p.includes('robots.txt')));
+  assert.ok(problems.some((p) => p.includes('/gone/') && p.includes('no page')));
+  assert.ok(problems.some((p) => p.includes('wrong.test')));
+});
+
+test('a missing sitemap says why when the domain is unset', () => {
+  const { problems } = auditSitemap(build({ 'index.html': '' }, { origin: undefined }));
+  assert.match(problems[0]!, /domain/);
+});
+
+test('audit assembles every finding with the page it was found on', () => {
+  const report = audit(
+    build({
+      'index.html': '<img src="/x.png"><a href="/nope">n</a><a href="https://ext.test/">e</a>',
+      'about/index.html': '<img src="/y.png" alt="Y"><a href="/">home</a>',
+      'robots.txt': 'Sitemap: https://example.com/sitemap-index.xml',
+      'sitemap-index.xml':
+        '<sitemapindex><sitemap><loc>https://example.com/sitemap-0.xml</loc></sitemap></sitemapindex>',
+      'sitemap-0.xml': '<urlset><url><loc>https://example.com/</loc></url></urlset>',
+    }),
+  );
+  assert.deepEqual(report.missingAlt, [{ page: 'index.html', src: '/x.png' }]);
+  assert.deepEqual(report.brokenInternal, [{ page: 'index.html', href: '/nope' }]);
+  assert.deepEqual(report.external, ['https://ext.test/']);
+  assert.deepEqual(report.sitemap.problems, []);
+});