@cparkerwebm/webmonterey 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -11,6 +11,55 @@ build. See `/webm:upgrade`.
 
 ---
 
+## 1.2.0 — 2026-09-02
+
+### Added
+
+- **Every site has a `/webmaster` page.** Injected by the integration, rendered with the site's
+  own chrome, indexable and in the sitemap. It says who designed, built and manages the site and
+  who to contact when something is wrong, carries its own share image (served from the package at
+  `/webmaster/og.png`, so a redesign reaches every site on `npm update`) and its own structured
+  data — a `WebPage` about the agency's `Organization`, using the same `@id` the agency's own site
+  declares. Every word is overridable through `copy.webmaster`. Off switch: `webmaster: false` on
+  the integration.
+
+- **`webm audit`** — the pre-launch checks only a build can answer: images with no `alt`
+  attribute (an explicit `alt=""` is fine), internal links that land on no page or Worker route,
+  and a sitemap that is missing, unadvertised, or lists a page that was not built. External links
+  are probed and reported as warnings. `/webm:launch` runs it and says how to act on each finding.
+
+- **Branch previews are a different build.** On any Workers Builds branch other than the
+  production one (`main`, or `productionBranch` on the integration), every page is noindex with
+  no canonical, there is no sitemap, `robots.txt` disallows everything, Google Tag Manager does
+  not load, and `/webmaster` emits no graph. Detected from the `WORKERS_CI_BRANCH` variable
+  Workers Builds injects; a local build is production. Mail on previews was already redirected by
+  the `workers.dev` hostname. Nothing to do on a site.
+
+- **`/webm:launch` asks two questions out loud** before the flip: is Google Tag Manager
+  configured and published for this site, and has the launch annotation been added in Google
+  Analytics. Neither is knowable from the repo, so the skill waits for the answer.
+
+### Changed
+
+- **The default share image is `public/opengraph.png`** (was `open-graph.png`). `webm new` seeds
+  the WebMonterey artwork there - the same image the `/webmaster` page uses - and a client replaces
+  it with their own; `webm doctor` flags the seed until they do. **On an existing site:** rename
+  `public/open-graph.png` to `public/opengraph.png`, or every page's `og:image` points at a file
+  that is not there.
+
+- **The footer credit is an internal link.** `Powered by WebMonterey` now goes to the site's own
+  `/webmaster` page instead of leaving the site; that page carries the one outbound link, with
+  the UTM parameters (`utm_campaign=webmaster`). The email footer keeps the outbound link — an
+  email cannot usefully point at a page on the site it is about.
+
+  **On an existing site:** the import moves —
+  `@cparkerwebm/webmonterey/webmonterey/credits/Credit.astro` is now
+  `@cparkerwebm/webmonterey/webmonterey/webmaster/Webmaster.astro`, and the module
+  `webmonterey/credits` is `webmonterey/webmaster`. The doctor check is `webmaster-credit`. The
+  site's `structuredData` component is not rendered on `/webmaster`; the page emits its own.
+
+---
+
 ## 1.1.0 — 2026-09-02
 
 ### Changed

package/dist/webm.mjs

@@ -1955,17 +1955,17 @@ var init_checks = __esm({
         }
       },
       {
-        id: "agency-credit",
-        title: "Something renders the agency credit",
-        silentAs: 'the site ships with no "Powered by WebMonterey" and nobody notices for months',
+        id: "webmaster-credit",
+        title: "Something renders the webmaster credit",
+        silentAs: 'the site ships with no "Powered by WebMonterey", the /webmaster page is orphaned, and nobody notices for months',
         run(ctx) {
           if (ctx.components.size === 0) return pass;
           if (ctx.site.domain === "webmonterey.com") return pass;
           for (const src of ctx.components.values()) {
-            if (/webmonterey\/credits/.test(stripComments(src))) return pass;
+            if (/webmonterey\/webmaster/.test(stripComments(src))) return pass;
           }
           return warn(
-            "no component imports @cparkerwebm/webmonterey/webmonterey/credits/Credit.astro. The footer component is where it goes."
+            "no component imports @cparkerwebm/webmonterey/webmonterey/webmaster/Webmaster.astro. The footer component is where it goes; it links to the /webmaster page."
           );
         }
       },
@@ -2087,17 +2087,17 @@ function parseJsonc(source) {
 }
 function readTree(root, dir, exts) {
   const out = /* @__PURE__ */ new Map();
-  const walk3 = (d) => {
+  const walk4 = (d) => {
     if (!existsSync8(d)) return;
     for (const entry2 of readdirSync6(d, { withFileTypes: true })) {
       const full = join7(d, entry2.name);
-      if (entry2.isDirectory()) walk3(full);
+      if (entry2.isDirectory()) walk4(full);
       else if (exts.some((e) => entry2.name.endsWith(e))) {
         out.set(relative3(root, full), readFileSync7(full, "utf8"));
       }
     }
   };
-  walk3(join7(root, dir));
+  walk4(join7(root, dir));
   return out;
 }
 function placeholderFiles(siteRoot) {
@@ -2213,6 +2213,243 @@ var init_doctor = __esm({
   }
 });
 
+// src/cli/audit.ts
+var audit_exports = {};
+__export(audit_exports, {
+  attr: () => attr,
+  audit: () => audit,
+  auditSitemap: () => auditSitemap,
+  hasAttr: () => hasAttr,
+  imagesWithoutAlt: () => imagesWithoutAlt,
+  links: () => links,
+  locs: () => locs,
+  resolves: () => resolves,
+  run: () => run6
+});
+import { existsSync as existsSync9, readdirSync as readdirSync7, readFileSync as readFileSync8, statSync as statSync3 } from "node:fs";
+import { join as join8, relative as relative4, resolve as resolve2 } from "node:path";
+function attr(tag, name) {
+  const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i").exec(tag);
+  if (!m) return null;
+  return m[1] ?? m[2] ?? m[3] ?? "";
+}
+function hasAttr(tag, name) {
+  return new RegExp(`\\s${name}(?=[\\s=>/])`, "i").test(tag);
+}
+function imagesWithoutAlt(html) {
+  const out = [];
+  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;
+}
+function links(html, origin) {
+  const internal = /* @__PURE__ */ new Set();
+  const external = /* @__PURE__ */ new Set();
+  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)) {
+      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] };
+}
+function resolves(href, input) {
+  let path = href.split("#")[0].split("?")[0];
+  try {
+    path = decodeURIComponent(path);
+  } catch {
+  }
+  if (!path.startsWith("/")) return true;
+  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(
+    (entry2) => entry2.endsWith("/*") ? bare === entry2.slice(0, -2) || bare.startsWith(entry2.slice(0, -1)) : entry2 === bare || entry2 === `${bare}/`
+  );
+}
+function locs(xml) {
+  return [...xml.matchAll(/<loc>\s*([^<]+?)\s*<\/loc>/g)].map((m) => m[1]);
+}
+function auditSitemap(input) {
+  const problems = [];
+  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 };
+}
+function audit(input) {
+  const missingAlt = [];
+  const brokenInternal = [];
+  const external = /* @__PURE__ */ new Set();
+  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)
+  };
+}
+function walk3(dir) {
+  if (!existsSync9(dir)) return [];
+  return readdirSync7(dir, { withFileTypes: true }).flatMap((e) => {
+    const full = join8(dir, e.name);
+    return e.isDirectory() ? walk3(full) : [full];
+  });
+}
+function parseJsonc2(source) {
+  const stripped = source.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (m, comment) => comment ? "" : m).replace(/,(\s*[}\]])/g, "$1");
+  return JSON.parse(stripped);
+}
+async function probe(urls) {
+  const bad = [];
+  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(8e3)
+        });
+        if (res.status === 405 || res.status === 403) {
+          res = await fetch(url, {
+            method: "GET",
+            redirect: "follow",
+            signal: AbortSignal.timeout(8e3)
+          });
+        }
+        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));
+}
+async function run6(argv2) {
+  const dist = resolve2(argv2.find((a) => !a.startsWith("-")) ?? "dist/client");
+  const noExternal = argv2.includes("--no-external");
+  if (!existsSync9(join8(dist, "index.html"))) {
+    console.error(`webm audit: no build at ${dist}. Run \`npm run build\` first.`);
+    return 1;
+  }
+  const siteRoot = process.cwd();
+  const files = walk3(dist);
+  const rels = new Set(files.map((f) => relative4(dist, f)));
+  const pages = new Map(
+    files.filter((f) => f.endsWith(".html")).map((f) => [relative4(dist, f), readFileSync8(f, "utf8")])
+  );
+  const wranglerPath = ["wrangler.jsonc", "wrangler.json"].map((f) => join8(siteRoot, f)).find(existsSync9);
+  const wrangler = wranglerPath ? parseJsonc2(readFileSync8(wranglerPath, "utf8")) : null;
+  const sitePath = join8(siteRoot, "webmonterey.json");
+  const site = existsSync9(sitePath) ? JSON.parse(readFileSync8(sitePath, "utf8")) : {};
+  const origin = site.domain && site.domain !== "CHANGEME" ? `https://${site.domain}` : void 0;
+  const report = audit({
+    pages,
+    exists: (rel) => rels.has(rel),
+    read: (rel) => rels.has(rel) && statSync3(join8(dist, rel)).isFile() ? readFileSync8(join8(dist, rel), "utf8") : null,
+    workerFirst: wrangler?.assets?.run_worker_first ?? [],
+    origin
+  });
+  let failed = 0;
+  const section = (ok, title) => 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(`
+${failed === 0 ? "audit clean" : `${failed} check(s) failed`}`);
+  return failed ? 1 : 0;
+}
+var SKIP_SCHEMES;
+var init_audit = __esm({
+  "src/cli/audit.ts"() {
+    "use strict";
+    SKIP_SCHEMES = /^(mailto:|tel:|sms:|javascript:|data:|#)/i;
+  }
+});
+
 // src/cli/codemods.ts
 function compareVersions(a, b) {
   const pa = a.split(".").map(Number);
@@ -2234,24 +2471,24 @@ var init_codemods = __esm({
 // src/cli/upgrade.ts
 var upgrade_exports = {};
 __export(upgrade_exports, {
-  run: () => run6
+  run: () => run7
 });
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync9, readFileSync as readFileSync8 } from "node:fs";
-import { join as join8 } from "node:path";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "node:fs";
+import { join as join9 } from "node:path";
 function git(siteRoot, args) {
   return execFileSync2("git", args, { cwd: siteRoot, encoding: "utf8" }).trim();
 }
 function installedVersion(siteRoot) {
-  const path = join8(siteRoot, "node_modules", PACKAGE, "package.json");
-  if (!existsSync9(path)) return null;
-  return JSON.parse(readFileSync8(path, "utf8")).version;
+  const path = join9(siteRoot, "node_modules", PACKAGE, "package.json");
+  if (!existsSync10(path)) return null;
+  return JSON.parse(readFileSync9(path, "utf8")).version;
 }
-function run6(argv2) {
+function run7(argv2) {
   const siteRoot = process.cwd();
   const target = argv2.find((a) => !a.startsWith("-")) ?? "latest";
   const dryRun = argv2.includes("--dry-run");
-  if (!existsSync9(join8(siteRoot, "webmonterey.json"))) {
+  if (!existsSync10(join9(siteRoot, "webmonterey.json"))) {
     console.error(`webm upgrade: no webmonterey.json here. Not a WebMonterey site.`);
     return 1;
   }
@@ -2317,9 +2554,9 @@ var init_upgrade = __esm({
 
 // bin/webm.mjs
 init_package_root();
-import { readFileSync as readFileSync9 } from "node:fs";
-import { join as join9 } from "node:path";
-var pkg = JSON.parse(readFileSync9(join9(PACKAGE_ROOT, "package.json"), "utf8"));
+import { readFileSync as readFileSync10 } from "node:fs";
+import { join as join10 } from "node:path";
+var pkg = JSON.parse(readFileSync10(join10(PACKAGE_ROOT, "package.json"), "utf8"));
 var COMMANDS = {
   new: {
     blurb: "Scaffold a new client site from a domain",
@@ -2341,6 +2578,10 @@ var COMMANDS = {
     blurb: "Check this site against the traps that fail silently",
     load: () => Promise.resolve().then(() => (init_doctor(), doctor_exports))
   },
+  audit: {
+    blurb: "Check a BUILD: image alt text, broken links, the sitemap. For launch.",
+    load: () => Promise.resolve().then(() => (init_audit(), audit_exports))
+  },
   upgrade: {
     blurb: "Move this site to a newer framework version",
     load: () => Promise.resolve().then(() => (init_upgrade(), upgrade_exports))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparkerwebm/webmonterey",
-  "version": "1.1.0",
+  "version": "1.2.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:
 

package/skills/start/SKILL.md

@@ -119,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

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