@piercebarney/whs-eleventy 2026.9.1

package/lib/content-check.js

@@ -0,0 +1,45 @@
+// The content-relevant slice of the gate, for an agent editing content
+// (CONTENT.md). Runs lint → validate → build → links — no browser, so no a11y
+// (that's backstopped by `npm run check` in bin/deploy before anything ships).
+//
+//   whs content-check
+//
+// Also warns — does not block — when the working tree has changes outside the
+// content set, so a stray code edit doesn't ride along in a `content:` commit.
+
+const { execSync } = require("node:child_process");
+
+// Files an agent following CONTENT.md is expected to touch.
+const CONTENT_SET = [/^src\/content\//, /^src\/_data\/nav\.js$/, /^src\/_data\/glossary\.js$/];
+
+function changedFiles() {
+  try {
+    const out = execSync("git status --porcelain", { encoding: "utf8" });
+    return out
+      .split("\n")
+      .map((l) => l.slice(3).trim())
+      .filter(Boolean)
+      .map((f) => (f.includes(" -> ") ? f.split(" -> ")[1] : f));
+  } catch {
+    return [];
+  }
+}
+
+const stray = changedFiles().filter((f) => !CONTENT_SET.some((re) => re.test(f)));
+if (stray.length) {
+  console.warn("\n⚠  changes outside the content set — these are code changes, not content:");
+  for (const f of stray) console.warn(`     ${f}`);
+  console.warn("   Commit them separately (a Claude Code task), or confirm they're intentional.\n");
+}
+
+const steps = ["lint", "validate", "build", "links"];
+for (const s of steps) {
+  process.stdout.write(`content-check: npm run ${s}\n`);
+  try {
+    execSync(`npm run ${s}`, { stdio: "inherit" });
+  } catch {
+    console.error(`\ncontent-check: '${s}' failed — fix it before committing.`);
+    process.exit(1);
+  }
+}
+console.log("\ncontent-check: ok — lint · validate · build · links");

package/lib/doctor.js

@@ -0,0 +1,416 @@
+// Infrastructure drift check (core.md#audit-page). Two tiers:
+//
+//   repo tier  — no network, always runs. Reads the files that encode
+//                cost/SEO-critical config (netlify.toml, .nvmrc, package.json,
+//                git config, the production _site/ output) and flags drift.
+//   live tier  — opt-in. Shells `netlify api getSite` (reusing whatever auth
+//                the Netlify CLI already has) to confirm the dashboard matches
+//                the repo: builds stopped, custom domain == site.url.
+//
+// Modes:
+//   whs doctor                    repo tier, print, exit 0 (unless a blocker
+//                                 like a tracked .env)
+//   whs doctor --live             repo + live, print, write cache
+//   whs doctor --deploy-preflight repo + live, and EXIT 1 on any cost/SEO-
+//                                 breaking mismatch. Run by bin/deploy after
+//                                 the prod build.
+//
+// The live snapshot is cached to .cache/doctor.json; src/_data/infra.js reads it
+// for the /audit/ "Infrastructure" tab (and re-runs the repo tier itself).
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { execSync } = require("node:child_process");
+const { ROOT, projectRequire } = require("./_project.js");
+
+const CACHE = path.join(ROOT, ".cache", "doctor.json");
+
+// Loaded lazily (inside the functions) so requiring this module for its API
+// doesn't fail in a dir without a project tree.
+const loadSite = () => projectRequire("src/_data/site.js");
+const loadThirdparties = () => projectRequire("src/_data/thirdparties.js");
+
+// Live values expected on every response — same patterns the /audit/ page uses.
+const HEADER_EXPECT = {
+  "Content-Security-Policy": /default-src 'self'/,
+  "X-Content-Type-Options": /nosniff/,
+  "X-Frame-Options": /DENY|SAMEORIGIN/,
+  "Referrer-Policy": /strict-origin/,
+  "Permissions-Policy": /geolocation=\(\)/,
+};
+
+const GATE_STAGES = ["lint", "validate", "test", "build", "links", "a11y"];
+
+function readText(rel) {
+  try {
+    return fs.readFileSync(path.join(ROOT, rel), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// ---- repo tier -------------------------------------------------------------
+
+function runRepoChecks({ preflight = false } = {}) {
+  const checks = [];
+  const add = (id, label, ok, severity, detail) =>
+    checks.push({ id, label, ok, severity: ok ? "ok" : severity, detail });
+  const site = loadSite();
+  const thirdparties = loadThirdparties();
+
+  // 1. Security headers declared in netlify.toml
+  const toml = readText("netlify.toml");
+  if (!toml) {
+    add("netlify-toml", "netlify.toml present", false, "blocker", "file missing");
+  } else {
+    const missing = Object.entries(HEADER_EXPECT)
+      .filter(([h, re]) => {
+        const m = toml.match(new RegExp(h + '\\s*=\\s*"([^"]+)"'));
+        return !m || !re.test(m[1]);
+      })
+      .map(([h]) => h);
+    add(
+      "security-headers",
+      "netlify.toml declares the 5 baseline security headers",
+      missing.length === 0,
+      "warn",
+      missing.length ? `missing / unexpected: ${missing.join(", ")}` : "all present",
+    );
+
+    // 2. Every origin the CSP grants is a declared third party
+    const cspMatch = toml.match(/Content-Security-Policy\s*=\s*"([^"]+)"/);
+    const cspOrigins = cspMatch
+      ? [...new Set((cspMatch[1].match(/https?:\/\/[^\s;'"]+/g) || []).map(originOf))]
+      : [];
+    const declaredOrigins = new Set(
+      thirdparties.flatMap((t) => [t.origin, ...(t.cspOrigins || [])]),
+    );
+    const undeclared = cspOrigins.filter((o) => !declaredOrigins.has(o));
+    add(
+      "csp-thirdparties",
+      "CSP origins all appear in src/_data/thirdparties.js",
+      undeclared.length === 0,
+      "warn",
+      undeclared.length ? `undeclared: ${undeclared.join(", ")}` : "in sync",
+    );
+  }
+
+  // 3. .nvmrc matches the running Node major
+  const nvmrc = (readText(".nvmrc") || "").trim().replace(/^v/, "");
+  const runningMajor = process.version.replace(/^v/, "").split(".")[0];
+  add(
+    "nvmrc-node",
+    ".nvmrc major matches the running Node",
+    nvmrc !== "" && nvmrc.split(".")[0] === runningMajor,
+    "warn",
+    `.nvmrc ${nvmrc || "(unset)"} · running ${process.version}`,
+  );
+
+  // 4. `npm run check` still runs every gate stage
+  let scripts = {};
+  try {
+    scripts = JSON.parse(readText("package.json")).scripts || {};
+  } catch {
+    /* handled below */
+  }
+  const check = scripts.check || "";
+  const absent = GATE_STAGES.filter((s) => !check.includes(s));
+  add(
+    "gate-stages",
+    "`npm run check` runs lint · validate · test · build · links · a11y",
+    check !== "" && absent.length === 0,
+    "warn",
+    absent.length ? `not referenced: ${absent.join(", ")}` : "complete",
+  );
+
+  // 5. git hooks are activated
+  let hooksPath = "";
+  try {
+    hooksPath = execSync("git config --get core.hooksPath", {
+      cwd: ROOT,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    /* unset */
+  }
+  add(
+    "hooks-path",
+    "core.hooksPath points at .githooks/",
+    hooksPath === ".githooks",
+    "warn",
+    hooksPath ? `= ${hooksPath}` : "unset — run `npm install`",
+  );
+
+  // 6. No .env committed
+  let tracked = "";
+  try {
+    tracked = execSync("git ls-files", { cwd: ROOT, encoding: "utf8" });
+  } catch {
+    /* not a git repo */
+  }
+  const envFiles = tracked
+    .split("\n")
+    .filter((f) => /(^|\/)\.env($|\.)/.test(f) && !/\.env\.example$/.test(f));
+  add(
+    "env-untracked",
+    "no .env file is tracked in git",
+    envFiles.length === 0,
+    "blocker",
+    envFiles.length ? `tracked: ${envFiles.join(", ")}` : "clean",
+  );
+
+  // 7. The built _site/ output is indexable only in production
+  const home = readText("_site/index.html");
+  if (home === null) {
+    add(
+      "prod-indexable",
+      "production _site/ output has no noindex",
+      !preflight,
+      "blocker",
+      preflight ? "_site/index.html not found — build before preflight" : "verified at deploy time",
+    );
+  } else {
+    const noindex = /<meta[^>]+name=["']robots["'][^>]+noindex/i.test(home);
+    if (preflight) {
+      add(
+        "prod-indexable",
+        "production _site/ output has no noindex",
+        !noindex,
+        "blocker",
+        noindex
+          ? "home page carries <meta robots noindex> — build was not production"
+          : "indexable",
+      );
+    } else {
+      add(
+        "prod-indexable",
+        "built _site/ output reflects its deploy target",
+        true,
+        "warn",
+        noindex ? "noindex present (expected for a preview build)" : "indexable (production build)",
+      );
+    }
+  }
+
+  // 8. site.url is a clean absolute origin
+  const cleanUrl = /^https:\/\/[^/]+\.[a-z]{2,}$/i.test(site.url);
+  add("site-url", "src/_data/site.js url is a clean https origin", cleanUrl, "warn", site.url);
+
+  return checks;
+}
+
+// ---- live tier ------------------------------------------------------------
+
+function originOf(u) {
+  try {
+    return new URL(u).origin;
+  } catch {
+    return u;
+  }
+}
+
+function runLiveChecks({ preflight = false } = {}) {
+  const site = loadSite();
+  const siteId = (process.env.NETLIFY_SITE_ID || "").trim() || stateSiteId();
+  if (!siteId) {
+    return {
+      available: false,
+      reason: "no NETLIFY_SITE_ID and no .netlify/state.json",
+      checks: [],
+    };
+  }
+
+  let info;
+  try {
+    const raw = execSync(
+      `npx netlify-cli api getSite --data '${JSON.stringify({ site_id: siteId })}'`,
+      {
+        cwd: ROOT,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 30000,
+      },
+    );
+    info = JSON.parse(raw);
+  } catch (e) {
+    return {
+      available: false,
+      reason: `netlify api getSite failed (${(e.message || "").split("\n")[0]}) — CLI not logged in?`,
+      checks: [],
+    };
+  }
+
+  const checks = [];
+  const add = (id, label, ok, severity, detail) =>
+    checks.push({ id, label, ok, severity: ok ? "ok" : severity, detail });
+
+  const stopped = info.build_settings && info.build_settings.stop_builds === true;
+  add(
+    "stop-builds",
+    "Netlify continuous deployment is stopped",
+    !!stopped,
+    preflight ? "blocker" : "warn",
+    stopped
+      ? "stopped — a git push builds nothing"
+      : "ENABLED — a git push will auto-build and bill",
+  );
+
+  const wantHost = originOf(site.url).replace(/^https?:\/\//, "");
+  const domains = [
+    info.custom_domain,
+    info.name && `${info.name}.netlify.app`,
+    ...(info.domain_aliases || []),
+  ].filter(Boolean);
+  const domainOk = domains.includes(wantHost);
+  add(
+    "domain-match",
+    "site.url host is served by this Netlify project",
+    domainOk,
+    preflight ? "blocker" : "warn",
+    `site.url ${wantHost} · project serves ${domains.join(", ") || "(none)"}`,
+  );
+
+  const published = info.published_deploy && info.published_deploy.state;
+  add(
+    "published-deploy",
+    "project has a published production deploy",
+    published === "ready",
+    "warn",
+    `state: ${published || "none"}`,
+  );
+
+  return { available: true, siteId, siteName: info.name, checks };
+}
+
+function stateSiteId() {
+  try {
+    return (
+      JSON.parse(fs.readFileSync(path.join(ROOT, ".netlify", "state.json"), "utf8")).siteId || ""
+    );
+  } catch {
+    return "";
+  }
+}
+
+// ---- cache (for src/_data/infra.js) -------------------------------------
+
+function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(CACHE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(payload) {
+  try {
+    fs.mkdirSync(path.dirname(CACHE), { recursive: true });
+    fs.writeFileSync(CACHE, JSON.stringify(payload, null, 2));
+  } catch {
+    /* .cache may be read-only in CI; the console output is the source of truth */
+  }
+}
+
+// ---- compliance regression diff (core.md#compliance) --------------------
+// Warn (never block) when a chapter that was PASS at the last deploy is now
+// FAIL — a real regression, distinct from the still-open migration backlog.
+
+function complianceRegressions() {
+  const dir = path.join(ROOT, ".cache");
+  const load = (f) => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+    } catch {
+      return null;
+    }
+  };
+  const cur = load("compliance.json");
+  const last = load("compliance-last.json");
+  if (!cur) return { checked: false, regressions: [] };
+  const lastStatus = {};
+  if (last) for (const r of last.results || []) lastStatus[r.slug] = r.status;
+  const regressions = (cur.results || [])
+    .filter((r) => r.status === "FAIL" && lastStatus[r.slug] === "PASS")
+    .map((r) => `#${r.slug}: PASS -> FAIL (${r.note})`);
+  try {
+    fs.copyFileSync(path.join(dir, "compliance.json"), path.join(dir, "compliance-last.json"));
+  } catch {
+    /* best effort */
+  }
+  return { checked: true, regressions, hadBaseline: !!last };
+}
+
+// ---- CLI ----------------------------------------------------------------
+
+function print(title, checks) {
+  console.log(`\n${title}`);
+  if (!checks.length) {
+    console.log("  (none)");
+    return;
+  }
+  for (const c of checks) {
+    const mark = c.severity === "ok" ? "ok  " : c.severity === "blocker" ? "FAIL" : "warn";
+    console.log(`  ${mark}  ${c.label}${c.detail ? ` — ${c.detail}` : ""}`);
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const preflight = args.includes("--deploy-preflight");
+  const withLive = preflight || args.includes("--live");
+
+  const repo = runRepoChecks({ preflight });
+  print("Repo checks", repo);
+
+  let live = { available: false, reason: "live tier not requested (pass --live)", checks: [] };
+  if (withLive) {
+    live = runLiveChecks({ preflight });
+    if (live.available) print("Live checks (Netlify API)", live.checks);
+    else console.log(`\nLive checks skipped — ${live.reason}`);
+  }
+
+  if (withLive) {
+    writeCache({
+      generatedAt: new Date().toISOString(),
+      live: live.available
+        ? { checks: live.checks, siteName: live.siteName }
+        : { available: false, reason: live.reason },
+    });
+  }
+
+  if (preflight) {
+    const cr = complianceRegressions();
+    if (!cr.checked) {
+      console.log(
+        "\nCompliance diff skipped — no .cache/compliance.json (run `npm run compliance`).",
+      );
+    } else if (cr.regressions.length) {
+      console.log(
+        `\nCompliance regressions since last deploy (${cr.regressions.length}, warning only):`,
+      );
+      cr.regressions.forEach((r) => console.log(`  - ${r}`));
+    } else {
+      console.log(
+        `\nCompliance diff: no PASS -> FAIL since last deploy${cr.hadBaseline ? "" : " (first baseline)"}.`,
+      );
+    }
+  }
+
+  const blockers = [...repo, ...live.checks].filter((c) => c.severity === "blocker");
+  if (blockers.length) {
+    console.error(`\ndoctor: ${blockers.length} blocking issue(s):`);
+    blockers.forEach((c) => console.error(`  - ${c.label}: ${c.detail}`));
+    if (preflight || blockers.some((c) => c.id === "env-untracked")) {
+      console.error("\nRefusing to continue.");
+      process.exit(1);
+    }
+  }
+  console.log(
+    `\ndoctor: ${blockers.length ? "blockers present (non-preflight run)" : "no blockers"}.`,
+  );
+}
+
+if (require.main === module) main();
+
+module.exports = { runRepoChecks, runLiveChecks, readCache };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@piercebarney/whs-eleventy",
+  "version": "2026.9.1",
+  "description": "The web house style's Eleventy + Netlify tooling — the compliance sweep, the infra doctor, the link/CSP integrity check, and the a11y scan, shared by every project on the stack.",
+  "bin": {
+    "whs": "cli.js"
+  },
+  "files": [
+    "cli.js",
+    "lib/",
+    "scripts/",
+    "standard/",
+    "README.md"
+  ],
+  "scripts": {
+    "prepare": "node scripts/bundle-standard.js",
+    "lint": "prettier --check . && eslint .",
+    "test": "node --test test/*.test.js",
+    "check": "npm run lint && npm test"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/piercebarney/web-house-style.git",
+    "directory": "packages/whs-eleventy"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "axe-core": "^4.13.0",
+    "node-html-parser": "^9.0.2",
+    "sirv": "^3.0.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "eslint": "^9.39.5",
+    "globals": "^17.11.0",
+    "prettier": "^3.9.6"
+  }
+}

package/scripts/bundle-standard.js

@@ -0,0 +1,35 @@
+// Copies the standard's text into standard/ so the published package carries the
+// core.md + CHANGELOG.md the drift check reads. Runs as `prepare` — before
+// `npm pack` / `npm publish`, and on a local `file:` install.
+//
+// Source is the repo root, three levels up (packages/whs-eleventy/scripts →
+// repo). When that isn't there (the package was installed as a git dep, say)
+// but standard/ is already populated, this is a no-op. Never hard-fails an
+// install.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const REPO = path.join(__dirname, "..", "..", "..");
+const OUT = path.join(__dirname, "..", "standard");
+const FILES = ["core.md", "CHANGELOG.md"];
+
+const haveSource = FILES.every((f) => fs.existsSync(path.join(REPO, f)));
+const haveBundle = FILES.every((f) => fs.existsSync(path.join(OUT, f)));
+
+if (!haveSource) {
+  if (haveBundle) {
+    console.log("bundle-standard: no repo source, standard/ already populated — skipping");
+    process.exit(0);
+  }
+  console.warn(
+    "bundle-standard: no repo source and no bundled standard/ — the drift check will need WHS_STANDARD set",
+  );
+  process.exit(0);
+}
+
+fs.mkdirSync(OUT, { recursive: true });
+for (const f of FILES) {
+  fs.copyFileSync(path.join(REPO, f), path.join(OUT, f));
+}
+console.log(`bundle-standard: copied ${FILES.join(", ")} → standard/`);