@cparkerwebm/webmonterey 1.0.0 → 1.2.0

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
 
@@ -124,8 +149,8 @@ Public values - the Turnstile site key, a GTM container id - are not secrets. Th
 ## 7. D1, if the site uses it
 
 ```sh
-npx wrangler d1 migrations list webm-<slug>-db --remote
-npx wrangler d1 migrations apply webm-<slug>-db --remote
+npx wrangler d1 migrations list <slug> --remote
+npx wrangler d1 migrations apply <slug> --remote
 ```
 
 `--remote` is the step people forget. Local migrations do nothing in production, and local and
@@ -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:
 

package/skills/start/SKILL.md

@@ -35,19 +35,25 @@ cd <domain_with_underscores>
 ```
 
 It writes the identity files, a working contact form, a home page, the fleet skills, and runs
-`git init` and `npm install`. Nothing outside the directory is touched.
+`git init` and `npm install`. Nothing outside the directory is touched. The GitHub owner comes
+from `git config webm.org` (set once per machine) or `--org`; the staging inbox from
+`git config webm.stagingEmail`, falling back to `user.email`.
 
-**Three names, and they differ on purpose:**
+**One name, everywhere.** The domain minus its TLD is the GitHub repo, the Worker, the D1
+database, the R2 bucket and any KV namespace:
 
-|             | Example                                              |                              |
-| ----------- | ---------------------------------------------------- | ---------------------------- |
-| GitHub repo | `webmonterey/autire_com`                             | Full domain, **underscores** |
-| Slug        | `autire`                                             | Domain minus the TLD         |
-| Cloudflare  | `webm-autire`, `webm-autire-db`, `webm-autire-media` | The slug, prefixed           |
+| Domain             | Name           |
+| ------------------ | -------------- |
+| `example.com`      | `example`      |
+| `shop.example.com` | `shop-example` |
+| `example.co.uk`    | `example`      |
 
-The slug drops the TLD because a Worker named `webm-autire-com` puts `autire-com` into every
-preview hostname, and Chrome's lookalike check then warns the client the site looks fake.
-`autire.com` and `autire.org` both want `autire` - check the slug is free before committing.
+The TLD is dropped because a Worker named `example-com` puts `example-com` into every preview
+hostname, and Chrome's lookalike check then warns the client the site looks fake. A second
+resource of one kind for the same client takes a purpose suffix: `example-portal`.
+
+`example.com` and `example.org` both want `example`. Check the name is free in the account
+before committing; the second one gets a name chosen by you, not by the tool.
 
 ## 2. Create the GitHub repo
 
@@ -79,9 +85,9 @@ Create only what the site needs. A marketing site with a contact form needs D1;
 R2 until someone has a video.
 
 ```sh
-npx wrangler d1 create webm-<slug>-db --update-config     # writes the binding into wrangler.jsonc
-npx wrangler d1 migrations apply webm-<slug>-db --local
-npx wrangler r2 bucket create webm-<slug>-media           # only if media is going to R2
+npx wrangler d1 create <slug> --update-config     # writes the binding into wrangler.jsonc
+npx wrangler d1 migrations apply <slug> --local
+npx wrangler r2 bucket create <slug>              # only if media is going to R2
 ```
 
 Set `features.d1: true` once the binding exists. `features.turnstile` waits for `/webm:launch`,
@@ -94,8 +100,8 @@ forms.** Miss one and it returns 200 to curl and a 404 page to Chrome. `webm doc
 ## 5. Workers Builds
 
 Connect the repo in the Cloudflare dashboard: **Workers & Pages → Create → Import a repository**.
-The Worker name must be `webm-<slug>` exactly - Workers Builds fails on a mismatch with
-`wrangler.jsonc`.
+The Worker name must be the slug exactly as `wrangler.jsonc` has it - Workers Builds fails on a
+mismatch.
 
 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
@@ -113,5 +119,9 @@ Workers Builds comments the preview URL on every PR - that is the client's revie
 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. 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

@@ -122,8 +122,8 @@ wildcards, and the free tier allows 10 hostnames per widget.
 
 **Chrome's "This site looks fake" warning on preview links comes from the Worker's NAME.** Its
 lookalike-domain check flags "domains that embed other domain names within their own hostname",
-and a Worker called `webm-acme-com` puts `acme-com` into every preview hostname. That is why
-Workers are named `webm-<slug>` with the TLD dropped — `webm-acme` embeds nothing that reads as a
+and a Worker called `acme-com` puts `acme-com` into every preview hostname. That is why every
+resource is named by the slug with the TLD dropped — `acme` embeds nothing that reads as a
 domain. `webm new` does this; do not name a Worker after the full domain.
 
 If a warning still appears on a correctly named Worker it is a URL-shape false positive, not a
@@ -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.

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, []);
+});

package/src/cli/audit.ts

@@ -0,0 +1,323 @@
+/*
+ * `webm audit [dist/client]` - the pre-launch checks that only a BUILD can answer.
+ *
+ * `webm doctor` reads source. Some things are only visible in the output: whether every image
+ * that reached the page has alt text, whether every internal link lands on a file the build
+ * produced (or a route the Worker serves), whether the sitemap the build wrote is complete and
+ * advertised. Each is the kind of thing a launch checklist says to "check" and nobody does
+ * exhaustively by hand on a forty-page site.
+ *
+ * Pure where it can be: `audit()` takes the built files and returns findings, so the rules are
+ * tested with literal HTML. `run()` reads dist/ and, unless told not to, makes one request per
+ * unique external link - the one part that needs a network.
+ *
+ * WHAT IT DOES NOT DO: write alt text. It lists the images that have none; the launch skill is
+ * what looks at each one and writes the words. An empty `alt=""` is a valid declaration that an
+ * image is decorative and is not reported - only a MISSING attribute is.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+export interface AuditInput {
+  /** Relative html path -> contents, for every page in the build. */
+  pages: Map<string, string>;
+  /** Whether a relative path exists in the build output. */
+  exists: (rel: string) => boolean;
+  /** Read a relative non-html file from the build, or null. */
+  read: (rel: string) => string | null;
+  /** wrangler.jsonc's run_worker_first, so an on-demand route is not reported as broken. */
+  workerFirst: string[];
+  /** The production origin, for sitemap and external-link decisions. Undefined while unset. */
+  origin?: string;
+}
+
+export interface AuditReport {
+  missingAlt: { page: string; src: string }[];
+  brokenInternal: { page: string; href: string }[];
+  /** Unique external URLs, for the caller to probe. */
+  external: string[];
+  sitemap: { problems: string[]; urls: number };
+}
+
+/** The value of one attribute on a tag, or null when absent. Quoted or bare. */
+export function attr(tag: string, name: string): string | null {
+  const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i').exec(tag);
+  if (!m) return null;
+  return m[1] ?? m[2] ?? m[3] ?? '';
+}
+
+/** Whether an attribute is present at all, with or without a value. */
+export function hasAttr(tag: string, name: string): boolean {
+  return new RegExp(`\\s${name}(?=[\\s=>/])`, 'i').test(tag);
+}
+
+/** Every `<img>` on a page that declares no alt attribute at all. */
+export function imagesWithoutAlt(html: string): string[] {
+  const out: string[] = [];
+  for (const m of html.matchAll(/<img\b[^>]*>/gi)) {
+    const tag = m[0];
+    if (hasAttr(tag, 'alt')) continue;
+    out.push(attr(tag, 'src') ?? '(no src)');
+  }
+  return out;
+}
+
+const SKIP_SCHEMES = /^(mailto:|tel:|sms:|javascript:|data:|#)/i;
+
+/** The hrefs on a page, split into internal paths and external URLs. */
+export function links(html: string, origin?: string): { internal: string[]; external: string[] } {
+  const internal = new Set<string>();
+  const external = new Set<string>();
+  for (const m of html.matchAll(/<a\b[^>]*>/gi)) {
+    const href = attr(m[0], 'href');
+    if (!href || SKIP_SCHEMES.test(href)) continue;
+    if (/^https?:\/\//i.test(href)) {
+      /* A link to the site's own origin is internal - check it as a path. */
+      if (origin && href.startsWith(origin)) internal.add(href.slice(origin.length) || '/');
+      else external.add(href);
+      continue;
+    }
+    if (href.startsWith('//')) {
+      external.add(`https:${href}`);
+      continue;
+    }
+    internal.add(href);
+  }
+  return { internal: [...internal], external: [...external] };
+}
+
+/**
+ * Does an internal href land somewhere? A file the build wrote, in any of the forms the asset
+ * router would serve it under, or a route the Worker answers.
+ */
+export function resolves(href: string, input: Pick<AuditInput, 'exists' | 'workerFirst'>): boolean {
+  let path = href.split('#')[0]!.split('?')[0]!;
+  try {
+    path = decodeURIComponent(path);
+  } catch {
+    /* leave it */
+  }
+  if (!path.startsWith('/')) return true; /* relative to the page; not worth a false positive */
+  if (path === '/') return input.exists('index.html');
+
+  const bare = path.replace(/\/$/, '');
+  const rel = bare.slice(1);
+  if (input.exists(rel) || input.exists(`${rel}.html`) || input.exists(`${rel}/index.html`)) {
+    return true;
+  }
+  return input.workerFirst.some((entry) =>
+    entry.endsWith('/*')
+      ? bare === entry.slice(0, -2) || bare.startsWith(entry.slice(0, -1))
+      : entry === bare || entry === `${bare}/`,
+  );
+}
+
+/** `<loc>` values out of a sitemap document. */
+export function locs(xml: string): string[] {
+  return [...xml.matchAll(/<loc>\s*([^<]+?)\s*<\/loc>/g)].map((m) => m[1]!);
+}
+
+/**
+ * The sitemap the build wrote: present, advertised in robots.txt, every child present, every URL
+ * on the production origin and landing on a page.
+ */
+export function auditSitemap(input: AuditInput): AuditReport['sitemap'] {
+  const problems: string[] = [];
+  const index = input.read('sitemap-index.xml');
+  if (!index) {
+    return {
+      problems: [
+        input.origin
+          ? 'sitemap-index.xml was not built'
+          : 'no sitemap - `domain` in webmonterey.json is unset, so nothing has an absolute URL',
+      ],
+      urls: 0,
+    };
+  }
+
+  const robots = input.read('robots.txt') ?? '';
+  if (!/^Sitemap:\s*\S+/m.test(robots)) problems.push('robots.txt has no Sitemap: line');
+
+  let urls = 0;
+  for (const childUrl of locs(index)) {
+    const childRel = childUrl.replace(/^https?:\/\/[^/]+\//, '');
+    const child = input.read(childRel);
+    if (!child) {
+      problems.push(`${childRel} is listed in the index and was not built`);
+      continue;
+    }
+    for (const url of locs(child)) {
+      urls++;
+      if (input.origin && !url.startsWith(input.origin)) {
+        problems.push(`${url} is not on ${input.origin}`);
+        continue;
+      }
+      const path = url.replace(/^https?:\/\/[^/]+/, '') || '/';
+      if (!resolves(path, input)) problems.push(`${url} is in the sitemap and has no page`);
+    }
+  }
+  if (urls === 0) problems.push('the sitemap lists no URLs');
+  return { problems, urls };
+}
+
+export function audit(input: AuditInput): AuditReport {
+  const missingAlt: AuditReport['missingAlt'] = [];
+  const brokenInternal: AuditReport['brokenInternal'] = [];
+  const external = new Set<string>();
+
+  for (const [page, html] of input.pages) {
+    for (const src of imagesWithoutAlt(html)) missingAlt.push({ page, src });
+    const found = links(html, input.origin);
+    for (const href of found.internal) {
+      if (!resolves(href, input)) brokenInternal.push({ page, href });
+    }
+    for (const url of found.external) external.add(url);
+  }
+
+  return {
+    missingAlt,
+    brokenInternal,
+    external: [...external].sort(),
+    sitemap: auditSitemap(input),
+  };
+}
+
+/* ── the command ─────────────────────────────────────────────────────────────────────────── */
+
+function walk(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const full = join(dir, e.name);
+    return e.isDirectory() ? walk(full) : [full];
+  });
+}
+
+/** Strip // and /* comments so JSON.parse can read a .jsonc file. */
+function parseJsonc<T>(source: string): T {
+  const stripped = source
+    .replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (m, comment) => (comment ? '' : m))
+    .replace(/,(\s*[}\]])/g, '$1');
+  return JSON.parse(stripped) as T;
+}
+
+/**
+ * One request per unique external URL. HEAD first; a 405 gets a GET, because plenty of servers
+ * refuse HEAD and answer GET. Failures are reported as warnings, not failures: many sites block
+ * anything that is not a browser, and a link that a bot cannot fetch is not necessarily broken.
+ */
+async function probe(urls: string[]): Promise<{ url: string; status: string }[]> {
+  const bad: { url: string; status: string }[] = [];
+  const queue = [...urls];
+  const worker = async () => {
+    for (let url = queue.shift(); url; url = queue.shift()) {
+      try {
+        let res = await fetch(url, {
+          method: 'HEAD',
+          redirect: 'follow',
+          signal: AbortSignal.timeout(8000),
+        });
+        if (res.status === 405 || res.status === 403) {
+          res = await fetch(url, {
+            method: 'GET',
+            redirect: 'follow',
+            signal: AbortSignal.timeout(8000),
+          });
+        }
+        if (res.status >= 400) bad.push({ url, status: String(res.status) });
+      } catch (error) {
+        bad.push({ url, status: error instanceof Error ? error.name : 'error' });
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: 6 }, worker));
+  return bad.sort((a, b) => a.url.localeCompare(b.url));
+}
+
+export async function run(argv: string[]): Promise<number> {
+  const dist = resolve(argv.find((a) => !a.startsWith('-')) ?? 'dist/client');
+  const noExternal = argv.includes('--no-external');
+
+  if (!existsSync(join(dist, 'index.html'))) {
+    console.error(`webm audit: no build at ${dist}. Run \`npm run build\` first.`);
+    return 1;
+  }
+
+  const siteRoot = process.cwd();
+  const files = walk(dist);
+  const rels = new Set(files.map((f) => relative(dist, f)));
+  const pages = new Map(
+    files
+      .filter((f) => f.endsWith('.html'))
+      .map((f) => [relative(dist, f), readFileSync(f, 'utf8')]),
+  );
+
+  const wranglerPath = ['wrangler.jsonc', 'wrangler.json']
+    .map((f) => join(siteRoot, f))
+    .find(existsSync);
+  const wrangler = wranglerPath
+    ? parseJsonc<{ assets?: { run_worker_first?: string[] } }>(readFileSync(wranglerPath, 'utf8'))
+    : null;
+
+  const sitePath = join(siteRoot, 'webmonterey.json');
+  const site = existsSync(sitePath)
+    ? (JSON.parse(readFileSync(sitePath, 'utf8')) as { domain?: string })
+    : {};
+  const origin = site.domain && site.domain !== 'CHANGEME' ? `https://${site.domain}` : undefined;
+
+  const report = audit({
+    pages,
+    exists: (rel) => rels.has(rel),
+    read: (rel) =>
+      rels.has(rel) && statSync(join(dist, rel)).isFile()
+        ? readFileSync(join(dist, rel), 'utf8')
+        : null,
+    workerFirst: wrangler?.assets?.run_worker_first ?? [],
+    origin,
+  });
+
+  let failed = 0;
+  const section = (ok: boolean, title: string) => console.log(`${ok ? '  ok ' : 'FAIL '} ${title}`);
+
+  section(report.missingAlt.length === 0, `Every image declares alt text (${pages.size} pages)`);
+  for (const { page, src } of report.missingAlt)
+    console.log(`       ${page}: <img src="${src}"> has no alt attribute`);
+  if (report.missingAlt.length) {
+    failed++;
+    console.log(
+      `       Write alt text for each - what the image shows, in context - or alt="" if it is decorative.`,
+    );
+  }
+
+  section(
+    report.brokenInternal.length === 0,
+    'Every internal link lands on a page or a Worker route',
+  );
+  for (const { page, href } of report.brokenInternal) console.log(`       ${page}: ${href}`);
+  if (report.brokenInternal.length) failed++;
+
+  section(
+    report.sitemap.problems.length === 0,
+    `The sitemap is complete and advertised (${report.sitemap.urls} URLs)`,
+  );
+  for (const p of report.sitemap.problems) console.log(`       ${p}`);
+  if (report.sitemap.problems.length) failed++;
+
+  if (noExternal) {
+    console.log(`  --  ${report.external.length} external links not probed (--no-external)`);
+  } else if (report.external.length) {
+    const bad = await probe(report.external);
+    console.log(
+      `${bad.length ? 'warn ' : '  ok '} ${report.external.length} external links respond (${bad.length} did not)`,
+    );
+    for (const { url, status } of bad) console.log(`       ${status.padEnd(12)} ${url}`);
+    if (bad.length)
+      console.log(
+        `       Open each in a browser before deciding it is broken - many sites refuse bots.`,
+      );
+  } else {
+    console.log('  ok  no external links');
+  }
+
+  console.log(`\n${failed === 0 ? 'audit clean' : `${failed} check(s) failed`}`);
+  return failed ? 1 : 0;
+}