@stack-mode/site-manager-kit 0.0.0-stage → 1.44.0

package/audit/wiring-audit.mjs

@@ -0,0 +1,604 @@
+// The wiring audit: compares what a website's code uses, what Site Manager has for the site, and values the code keeps
+// its own copy of. Run in the website's folder with `npx site-manager-kit audit`. Read only: it never writes to Site
+// Manager. It writes .wiring/report.md (and report.json) and exits 1 when anything is Not wired or missing in Site
+// Manager, so it can gate CI. docs/wiring.md in Site Manager explains the process this checks.
+//
+// Plain JavaScript with no dependencies, so it runs before anything is built.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { createRequire, register } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const STATUS = {
+  wired: "Wired",
+  not_wired: "Not wired",
+  missing: "Missing in Site Manager",
+  hard_coded: "Hard-coded",
+  unknown: "Unknown",
+  info: "Note",
+};
+const FAILING = new Set(["not_wired", "missing"]);
+
+// Which kit readers (or API paths) show that a site reads a Site Manager section. Sections not listed here have
+// nothing a website reads (ADMIN_ONLY), or are new to the audit (reported as Unknown until added here).
+export const MODULE_READERS = {
+  business_info: { names: ["getSite"], paths: ["/site"] },
+  site_copy: { names: ["getCopy", "copyText", "copyImage", "copyLink", "copyRecords"], paths: ["/copy"] },
+  reviews: { names: ["getReviews", "getReviewPlatforms"], paths: ["/reviews"] },
+  floor_plans: { names: ["getFloorPlans", "getFloorPlan", "getUnitMaps"], paths: ["/floor-plans", "/unit-maps"] },
+  amenities: { names: ["getAmenities"], paths: ["/amenities"] },
+  fees: { names: ["getFees"], paths: ["/fees"] },
+  specials: { names: ["getSpecials"], paths: ["/specials"] },
+  forms: { names: ["getForm", "submitForm", "formAction"], paths: ["/forms"] },
+  bookings: { names: ["getBookingSlots"], paths: ["/slots"] },
+  events: { names: ["getEvents", "getEvent"], paths: ["/events"] },
+  blog: { names: ["getPosts", "getPost", "getBlogCategories", "getBlogCategory", "getBlogFeed", "getBlogTags", "rssRoute"], paths: ["/blog"] },
+  locations: { names: ["getLocations"], paths: ["/locations"] },
+  nearby_places: { names: ["getNearbyPlaces"], paths: ["/nearby-places"] },
+  seo: { names: ["pageMetadata", "buildMetadata", "defaultMetadata", "buildSitemap", "buildRobots"], paths: ["/pages/meta", "/sitemap", "/robots"] },
+  legal: { names: ["getLegal", "getLegalDoc"], paths: ["/legal"] },
+  services: { names: ["getServices", "getService"], paths: ["/services"] },
+  pet_policy: { names: ["getPetPolicy"], paths: ["/pet-policy"] },
+  parking: { names: ["getParking"], paths: ["/parking"] },
+  waitlist: { names: ["getWaitlistOptions", "joinWaitlist", "waitlistAction"], paths: ["/waitlist"] },
+  listings: { names: ["getListings", "getListing", "getSoldListings", "getPaymentDefaults"], paths: ["/listings", "/payment-defaults"] },
+  team_members: { names: ["getTeam", "getTeamMember"], paths: ["/team"] },
+  areas: { names: ["getAreas", "getArea"], paths: ["/areas"] },
+  faq: { names: ["getFaq", "getFaqSet"], paths: ["/faq"] },
+  glossary: { names: ["getGlossary", "getGlossaryTerm"], paths: ["/glossary"] },
+  announcements: { names: ["getAnnouncements"], paths: ["/announcements"] },
+  downloads: { names: ["getDownloads"], paths: ["/downloads"] },
+  policies: { names: ["getPolicies"], paths: ["/policies"] },
+  resident_resources: { names: ["getResidentResources"], paths: ["/resident-resources"] },
+  visual_editor: { names: ["VisualEditing", "visualFrameHeaders", "allowVisualFrames", "withSiteManager"], paths: [] },
+  site_chat: { names: ["SiteChat"], paths: ["/chat"], imports: ["site-manager-kit/chat-route"] },
+  analytics: { names: ["SiteAnalytics"], paths: [] },
+};
+export const ADMIN_ONLY = new Set(["users", "media", "support", "texting", "leads", "review_requests", "calendar", "publishing", "brand_voice", "pms_sync", "rent_roll", "reports", "portfolio", "tour", "connections", "integrations", "backups", "email", "setup", "sites"]);
+
+const CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|json)$/;
+const IMAGE_EXT = /\.(png|jpe?g|webp|avif|gif|svg|ico)$/i;
+const SKIP_DIRS = new Set(["node_modules", ".next", ".git", ".wiring", ".vercel", "out", "build", "dist", "coverage", ".turbo"]);
+const MAX_WHERE = 15;
+
+// ---------------------------------------------------------------- small pure helpers (tested)
+
+/** BLUEPRINT_* values from a .env file's text. Quotes are removed; other variables are ignored. */
+export function parseEnv(text) {
+  const out = {};
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(/^\s*(?:export\s+)?(BLUEPRINT_[A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+    if (!m) continue;
+    let v = m[2].trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    out[m[1]] = v;
+  }
+  return out;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** A pattern for a US phone number however it's typed: (775) 544-9262, 775.544.9262, +17755449262. */
+export function phonePattern(phone) {
+  let d = String(phone ?? "").replace(/\D/g, "");
+  if (d.length === 11 && d.startsWith("1")) d = d.slice(1);
+  if (d.length !== 10) return null;
+  const sep = "[\\s.\\-]*";
+  return new RegExp(`(?<!\\d)(?:\\+?1${sep})?\\(?${d.slice(0, 3)}\\)?${sep}${d.slice(3, 6)}${sep}${d.slice(6)}(?!\\d)`);
+}
+
+/** A quoted string literal equal to the value, ignoring case. */
+export const literalPattern = (value) => new RegExp(`(["'\`])${escapeRe(String(value).trim())}\\1`, "i");
+
+/** The value anywhere in a line, ignoring case. */
+export const containsPattern = (value) => new RegExp(escapeRe(String(value).trim()), "i");
+
+/** A URL without its scheme, www or trailing slash, so https://www.x.com/a/ and x.com/a match. */
+export function bareUrl(url) {
+  return String(url ?? "")
+    .trim()
+    .replace(/^https?:\/\//i, "")
+    .replace(/^www\./i, "")
+    .replace(/\/+$/, "");
+}
+
+/** A file name reduced to letters and digits, for matching a public/ file against a Site Manager photo's address. */
+export function fileStem(name) {
+  const base = decodeURIComponent(String(name).split(/[?#]/)[0].split("/").pop() ?? "");
+  return base.replace(/\.[a-z0-9]+$/i, "").toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+/** Copy key names a line asks for by name: COPY["a.b"], copyText("a.b"), <CopyText k="a.b">. */
+export function keyRefsIn(line) {
+  const out = [];
+  const re = /(?:COPY\[\s*|\bcopy(?:Text|Image|Link|Records|Plain|Rich)\(\s*|\bk=\{?\s*)(["'`])([a-z0-9]+(?:[._-][a-z0-9]+)+)\1/g;
+  for (const m of line.matchAll(re)) out.push(m[2]);
+  return out;
+}
+
+/** The declared copy keys a module exports: the kit's defineCopyKeys result, or a plain object of definitions. */
+export function declaredFrom(mod) {
+  const candidates = [mod.COPY, mod.default, ...Object.values(mod)];
+  for (const c of candidates) {
+    if (!c || typeof c !== "object") continue;
+    const defs = c.__defs && typeof c.__defs === "object" ? c.__defs : c;
+    const entries = Object.entries(defs);
+    if (entries.length && entries.every(([, d]) => d && typeof d === "object" && typeof d.label === "string" && typeof d.kind === "string")) {
+      return new Map(entries.map(([k, d]) => [k, d]));
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------- the site's files
+
+function walk(dir, root, out, ignore) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    const rel = path.relative(root, full).split(path.sep).join("/");
+    if (ignore.some((p) => rel === p || rel.startsWith(p.replace(/\/?$/, "/")))) continue;
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) walk(full, root, out, ignore);
+    } else out.push(rel);
+  }
+}
+
+/** The site's code (not tests) as lines, and its files in public/. */
+export function readSite(siteDir, opts = {}) {
+  const ignore = opts.ignore ?? [];
+  const all = [];
+  for (const r of opts.roots ?? ["src", "app", "components", "lib", "content", "config"]) {
+    if (existsSync(path.join(siteDir, r))) walk(path.join(siteDir, r), siteDir, all, ignore);
+  }
+  const files = [];
+  for (const rel of all) {
+    if (!CODE_EXT.test(rel) || /\.(test|spec)\.[a-z]+$/.test(rel) || rel.includes("__tests__/")) continue;
+    const text = readFileSync(path.join(siteDir, rel), "utf8");
+    files.push({ rel, text, lines: text.split(/\r?\n/), usesKit: text.includes("site-manager-kit") });
+  }
+  const pub = [];
+  if (existsSync(path.join(siteDir, "public"))) walk(path.join(siteDir, "public"), path.join(siteDir, "public"), pub, []);
+  return { files, publicFiles: pub.filter((p) => IMAGE_EXT.test(p)) };
+}
+
+/** Every line matching the pattern, as file:line. */
+export function findAll(files, re, filter = () => true) {
+  const out = [];
+  for (const f of files) {
+    if (!filter(f)) continue;
+    f.lines.forEach((line, i) => {
+      if (re.test(line)) out.push({ file: f.rel, line: i + 1 });
+    });
+  }
+  return out;
+}
+
+const mentions = (files, re) => files.some((f) => re.test(f.text));
+
+/** Whether the site's code reads a section: a kit reader imported or called, or its API path requested. */
+export function readsModule(files, readers) {
+  const kitFiles = files.filter((f) => f.usesKit);
+  if (readers.names.some((n) => mentions(kitFiles, new RegExp(`\\b${n}\\b`)))) return true;
+  if ((readers.imports ?? []).some((i) => mentions(files, new RegExp(`["']${escapeRe(i)}["']`)))) return true;
+  return readers.paths.some((p) => mentions(kitFiles, new RegExp(`["'\`](?:/api/v1)?${escapeRe(p)}(?:[/?"'\`$])`)));
+}
+
+// ---------------------------------------------------------------- loading the declared copy keys
+
+function tsconfigAliases(siteDir, ts) {
+  const file = path.join(siteDir, "tsconfig.json");
+  if (!existsSync(file)) return [];
+  const parsed = ts.readConfigFile(file, ts.sys.readFile).config ?? {};
+  const base = path.resolve(siteDir, parsed.compilerOptions?.baseUrl ?? ".");
+  return Object.entries(parsed.compilerOptions?.paths ?? {}).map(([from, targets]) => ({
+    prefix: from.replace(/\*$/, ""),
+    targets: targets.map((t) => path.resolve(base, t.replace(/\*$/, "")) + (t.endsWith("/*") ? path.sep : "")),
+  }));
+}
+
+let hooksRegistered = false;
+
+/** The keys the site declares in its copy keys file, loaded with the site's own TypeScript. */
+export async function loadDeclaredKeys(siteDir, keysFile) {
+  const file = path.resolve(siteDir, keysFile);
+  if (!existsSync(file)) return { error: `${keysFile} doesn't exist.` };
+  let ts;
+  try {
+    ts = createRequire(path.join(siteDir, "package.json"))("typescript");
+  } catch {
+    return { error: "TypeScript isn't installed in this site (run npm install first)." };
+  }
+  if (!hooksRegistered) {
+    register(new URL("./ts-hooks.mjs", import.meta.url), { data: { siteDir, aliases: tsconfigAliases(siteDir, ts) } });
+    hooksRegistered = true;
+  }
+  try {
+    const mod = await import(pathToFileURL(file).href);
+    const declared = declaredFrom(mod);
+    return declared ? { declared } : { error: `${keysFile} doesn't export its copy keys (export const COPY = defineCopyKeys(...)).` };
+  } catch (e) {
+    return { error: `${keysFile} couldn't be loaded: ${String(e?.message ?? e).split("\n")[0]}` };
+  }
+}
+
+// ---------------------------------------------------------------- Site Manager
+
+export function makeApi(base, key, fetchImpl = fetch) {
+  return async (p) => {
+    const res = await fetchImpl(`${base.replace(/\/+$/, "")}/api/v1${p}`, { headers: { authorization: `Bearer ${key}` }, cache: "no-store" });
+    const json = await res.json().catch(() => null);
+    return { status: res.status, data: json?.data ?? null, meta: json?.meta ?? null, code: json?.error?.code ?? null };
+  };
+}
+
+/** Every photo address found anywhere in a Site Manager answer. */
+function imageUrls(value, out = new Set()) {
+  if (typeof value === "string") {
+    if (/^https?:\/\//.test(value) && IMAGE_EXT.test(value.split(/[?#]/)[0])) out.add(value);
+  } else if (Array.isArray(value)) value.forEach((v) => imageUrls(v, out));
+  else if (value && typeof value === "object") Object.values(value).forEach((v) => imageUrls(v, out));
+  return out;
+}
+
+/**
+ * Posts the audit's items to Site Manager (POST /api/v1/wiring), where the site's Wiring tab, score and Portfolio
+ * column show them. Needs an audit key: website keys are refused (403 audit_key_required). Never throws.
+ */
+export async function uploadResult(base, key, result, kitVersion, fetchImpl = fetch) {
+  const body = { kitVersion, ranAt: new Date().toISOString(), items: result.items.slice(0, 3000) };
+  let res;
+  try {
+    res = await fetchImpl(`${base.replace(/\/+$/, "")}/api/v1/wiring`, { method: "POST", headers: { authorization: `Bearer ${key}`, "content-type": "application/json" }, body: JSON.stringify(body) });
+  } catch (e) {
+    return { ok: false, message: `Couldn't reach Site Manager to upload the result (${e.message}).` };
+  }
+  const json = await res.json().catch(() => null);
+  if (res.status === 201) {
+    const d = json?.data ?? {};
+    return { ok: true, message: `Uploaded to Site Manager${d.score === null || d.score === undefined ? "" : `: wired ${d.score}%, ${d.needsAttention} need attention`}.` };
+  }
+  const code = json?.error?.code;
+  if (code === "audit_key_required") return { ok: false, message: "Site Manager refused the upload: it needs a Wiring audit key (API Keys tab, Kind: Wiring audit) in BLUEPRINT_AUDIT_KEY." };
+  if (res.status === 401) return { ok: false, message: "Site Manager refused the key (401). Check BLUEPRINT_AUDIT_KEY." };
+  if (res.status === 429) return { ok: false, message: "Site Manager has had too many uploads for this site in the last hour. Try again later." };
+  return { ok: false, message: `Site Manager answered ${res.status}${code ? ` (${code})` : ""} to the upload.` };
+}
+
+// ---------------------------------------------------------------- the audit
+
+/**
+ * Runs every check. `api` answers Site Manager paths; `declaredResult` is loadDeclaredKeys' answer. Pure apart from
+ * `api`, so tests give it fixtures.
+ */
+export async function audit({ site: siteFiles, api, declaredResult, keysFile, hasCopyKeysRoute }) {
+  const items = [];
+  const add = (area, status, name, detail, fix = null, where = []) => items.push({ area, status, name, detail, fix, where: where.slice(0, MAX_WHERE), more: Math.max(0, where.length - MAX_WHERE) });
+  const { files, publicFiles } = siteFiles;
+
+  const siteRes = await api("/site");
+  if (siteRes.status === 401) throw new Error("Site Manager refused the API key (401). Check BLUEPRINT_API_KEY.");
+  if (siteRes.status !== 200 || !siteRes.data) throw new Error(`Site Manager answered ${siteRes.status} for /site${siteRes.code ? ` (${siteRes.code})` : ""}.`);
+  const sm = siteRes.data;
+  const modules = new Set(sm.modules ?? []);
+  const smImages = imageUrls(sm);
+
+  // ---- Copy keys
+  const declared = declaredResult.declared ?? null;
+  if (!declared) add("Copy keys", "unknown", keysFile, `The site's copy keys couldn't be read: ${declaredResult.error}`, "Declare every piece of built-in text in src/copy-keys.ts with defineCopyKeys (see the site starter).");
+  if (modules.has("site_copy")) {
+    if (!hasCopyKeysRoute) add("Copy keys", "not_wired", "Copy keys route", "The website has no app/api/blueprint/copy-keys route, so Site Manager's Sync from Website can't read its keys.", 'Add app/api/blueprint/copy-keys/route.ts: export const GET = copyKeysRoute(COPY) (site-manager-kit/copy-keys-route).');
+    const copyRes = await api("/copy");
+    const smCopy = copyRes.status === 200 && copyRes.data ? copyRes.data : {};
+    imageUrls(smCopy, smImages);
+    const refs = new Map();
+    for (const f of files) f.lines.forEach((line, i) => keyRefsIn(line).forEach((k) => (refs.has(k) ? refs.get(k) : refs.set(k, []).get(k)).push({ file: f.rel, line: i + 1 })));
+    let wired = 0;
+    for (const [k, def] of declared ?? []) {
+      const v = smCopy[k];
+      if (!v) add("Copy keys", "missing", k, `Declared in ${keysFile} as ${def.kind} ("${def.label}") but Site Manager doesn't have it.`, def.kind === "link" || def.kind === "records" ? "Add it by hand in Site Manager's Copy Keys (links and record picks can't be synced)." : "Deploy, then press Sync from Website in Site Copy.");
+      else if (v.kind !== def.kind) add("Copy keys", "not_wired", k, `Site Manager has it as ${v.kind}, the website declares ${def.kind}, so the site can't show what's saved.`, "Change the kind in one place so they match (Copy Keys in Site Manager, or the declaration).");
+      else wired++;
+    }
+    for (const [k, where] of refs) {
+      if (declared?.has(k)) continue;
+      if (smCopy[k]) add("Copy keys", "hard_coded", k, "Used in code by name but not declared, so Sync from Website won't keep its label and starting text in step.", `Declare it in ${keysFile}.`, where);
+      else add("Copy keys", "missing", k, "Used in code by name, but neither declared nor in Site Manager. The page shows nothing (or its fallback) for it.", `Declare it in ${keysFile}, deploy, then Sync from Website.`, where);
+    }
+    for (const [k, v] of Object.entries(smCopy)) {
+      if (declared?.has(k) || refs.has(k)) continue;
+      const seen = findAll(files, literalPattern(k));
+      if (seen.length) {
+        wired++;
+        continue;
+      }
+      add("Copy keys", declared ? "not_wired" : "unknown", k, `In Site Manager (${v.kind}${v.pagePath ? `, page ${v.pagePath}` : ""}) but the website never asks for it, so edits to it show nowhere.`, "Show it on the page and declare it, or remove the key in Copy Keys if the text is gone from the site.");
+    }
+    add("Copy keys", "wired", `${wired} copy keys`, "Declared by the website and present in Site Manager with the same kind.");
+  }
+
+  // ---- Business Info
+  const b = sm.business ?? {};
+  const bizFiles = files.filter((f) => /\bbusiness\b/.test(f.text));
+  const readsBusiness = readsModule(files, MODULE_READERS.business_info);
+  const readsField = (re) => readsBusiness && mentions(bizFiles, re);
+  const facts = [
+    { name: "Business name", value: b.displayName, read: /[.?]displayName\b/, pattern: b.displayName && literalPattern(b.displayName) },
+    { name: "Legal name", value: b.legalName, read: /[.?]legalName\b/, pattern: b.legalName && literalPattern(b.legalName) },
+    { name: "Phone", value: b.phone, read: /[.?]phone\b/, pattern: phonePattern(b.phone) },
+    { name: "Email", value: b.email, read: /[.?]email\b/, pattern: b.email && containsPattern(b.email) },
+    { name: "Address", value: b.address?.line1, read: /[.?]address\b/, pattern: b.address?.line1 && containsPattern(b.address.line1) },
+    { name: "Hours", value: b.hours || b.hoursNote, read: /[.?]hours(Note)?\b/, pattern: b.hoursNote && literalPattern(b.hoursNote) },
+    { name: "Map position", value: b.geo, read: /[.?]geo\b/, pattern: null },
+    { name: "Website address", value: sm.websiteUrl, read: /[.?]websiteUrl\b/, pattern: sm.websiteUrl && containsPattern(`://${bareUrl(sm.websiteUrl).replace(/\/.*$/, "")}`) },
+  ];
+  for (const s of b.social ?? []) facts.push({ name: `Social: ${s.network}`, value: s.url, read: /[.?]social\b/, pattern: s.url && containsPattern(bareUrl(s.url)) });
+  for (const fact of facts) {
+    if (!fact.value || (typeof fact.value === "object" && !Object.keys(fact.value).length)) {
+      add("Business Info", "info", fact.name, "Not set in Site Manager.");
+      continue;
+    }
+    const read = readsField(fact.read);
+    const where = fact.pattern ? findAll(files, fact.pattern) : [];
+    if (!read) add("Business Info", "not_wired", fact.name, `Set in Site Manager but the site never reads it${where.length ? "; the site shows its own copy instead" : ""}.`, "Read it from getSite().business (or the site's settings helper) and delete the built-in copy.", where);
+    else if (where.length) add("Business Info", "hard_coded", fact.name, "Read from Site Manager, but the code also keeps its own copy (a fallback or a second place that shows it). If the value is cleared or changed in Site Manager, these places can show the old one.", "Show the Site Manager value everywhere and drop the built-in copy, or keep it only as a fallback that's never shown when Site Manager has a value.", where);
+    else add("Business Info", "wired", fact.name, "Read from Site Manager.");
+  }
+
+  // ---- Sections (modules)
+  for (const key of [...modules].sort()) {
+    if (key === "seo") continue; // checked piece by piece below
+    const readers = MODULE_READERS[key];
+    if (!readers) {
+      add("Sections", ADMIN_ONLY.has(key) ? "info" : "unknown", key, ADMIN_ONLY.has(key) ? "On; nothing on the website reads it (admin only)." : "On, and this audit doesn't know how a website reads it yet.", ADMIN_ONLY.has(key) ? null : "Add it to MODULE_READERS in the kit's audit/wiring-audit.mjs.");
+      continue;
+    }
+    if (readsModule(files, readers)) add("Sections", "wired", key, "On in Site Manager and read by the site.");
+    else add("Sections", "not_wired", key, "On in Site Manager, but the site never reads it, so the client can edit it and nothing changes on the website.", "Show it on the site with the kit's reader, or switch the section off for this site.");
+  }
+  for (const [key, readers] of Object.entries(MODULE_READERS)) {
+    if (!modules.has(key) && key !== "seo" && readsModule(files, readers)) add("Sections", "info", key, "Off in Site Manager, but the code reads it. The kit answers module_off, so whatever shows comes from the site's own fallback.");
+  }
+
+  // ---- SEO and redirects
+  if (modules.has("seo")) {
+    const seoChecks = [
+      { name: "Page titles and descriptions", names: ["pageMetadata", "buildMetadata", "defaultMetadata"], paths: ["/pages/meta"] },
+      { name: "Sitemap", names: ["buildSitemap", "sitemap"], paths: ["/sitemap"] },
+      { name: "robots.txt and indexing", names: ["buildRobots", "robots"], paths: ["/robots"] },
+      { name: "Redirects", names: ["handleRedirect", "withSiteManager", "buildRedirectMap"], paths: ["/redirects"] },
+    ];
+    for (const c of seoChecks) {
+      if (readsModule(files, { names: c.names, paths: c.paths })) add("SEO", "wired", c.name, "Read from Site Manager.");
+      else add("SEO", "not_wired", c.name, "Search Listings has it, but the site doesn't read it.", "Use the kit's helper for it (see the kit README).");
+    }
+  }
+
+  // ---- Forms
+  if (modules.has("forms")) {
+    const keys = new Map();
+    const re = /\b(?:getForm|submitForm|formAction|getBookingSlots)\(\s*["'`]([a-z0-9_-]+)["'`]|\b(?:form|formKey|[a-z][a-zA-Z0-9]*Form)\s*:\s*["']([a-z0-9][a-z0-9_-]*)["']/g;
+    for (const f of files) f.lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        const k = m[1] ?? m[2];
+        (keys.get(k) ?? keys.set(k, []).get(k)).push({ file: f.rel, line: i + 1 });
+      }
+    });
+    for (const [k, where] of keys) {
+      const r = await api(`/forms/${encodeURIComponent(k)}`);
+      if (r.status === 200) add("Forms", "wired", k, "The form exists in Site Manager.", null, where);
+      else if (r.status === 404) add("Forms", "missing", k, "The site sends to this form, but Site Manager has no form with this key, so submissions fail.", "Add the form in Site Manager's Forms with this key, or fix the key in code.", where);
+      else add("Forms", "unknown", k, `Site Manager answered ${r.status}.`, null, where);
+    }
+    if (!keys.size) add("Forms", "info", "Form keys", "No form key is written in the code by name, so the audit can't check them one by one. Check each form submits on the preview.");
+  }
+
+  // ---- Lists the site keeps its own copy of: review platforms, blog and glossary categories
+  const lists = [];
+  if (modules.has("reviews")) {
+    const r = await api("/reviews");
+    imageUrls(r.data, smImages);
+    imageUrls(r.meta, smImages);
+    lists.push({ area: "Review platforms", names: (r.meta?.platforms ?? []).map((p) => p.label), reader: ["getReviewPlatforms"] });
+  }
+  if (modules.has("blog")) {
+    const r = await api("/blog/categories");
+    lists.push({ area: "Blog categories", names: (r.data ?? []).map((c) => c.name), reader: ["getBlogCategories", "/blog/categories"] });
+  }
+  if (modules.has("glossary")) {
+    const r = await api("/glossary");
+    lists.push({ area: "Glossary categories", names: (r.data?.categories ?? []).map((c) => c.name), reader: ["getGlossary", "/glossary"] });
+  }
+  for (const l of lists) {
+    const reads = readsModule(files, { names: l.reader.filter((n) => !n.startsWith("/")), paths: l.reader.filter((n) => n.startsWith("/")) });
+    for (const name of l.names.filter((n) => n && n.trim().length >= 3)) {
+      const where = findAll(files, literalPattern(name));
+      if (where.length) add(l.area, "hard_coded", name, `${reads ? "Read from Site Manager, but the" : "The"} code also has its own copy of this name${reads ? "" : " and never reads the list"}, so a rename, a new entry or a new order in Site Manager may not show.`, "Read the list (names and order) from Site Manager and drop the built-in list.", where);
+      else add(l.area, reads ? "wired" : "not_wired", name, reads ? "Read from Site Manager." : "In Site Manager, but the site never reads this list.", reads ? null : "Read the list from Site Manager.");
+    }
+  }
+
+  // ---- Brand: Site Manager's website API doesn't send the logo or colors yet, so only the site's side is checked.
+  const logos = publicFiles.filter((p) => /logo/i.test(p));
+  const logoRefs = logos.flatMap((p) => findAll(files, containsPattern(`/${p}`)).map((w) => ({ ...w, p })));
+  add("Brand", "unknown", "Logo and colors", "Site Manager's website API doesn't send the logo or brand colors yet, so the site can't read them.", "Next step for Site Manager: add the logo and accent color to /api/v1/site (additive).");
+  if (logoRefs.length) add("Brand", "hard_coded", "Logo files in public/", `The site shows ${new Set(logoRefs.map((w) => w.p)).size} logo file(s) from public/.`, "Keep until Site Manager sends the logo; then read it from there.", logoRefs);
+
+  // ---- Photos in public/
+  const declaredImages = new Map([...(declared ?? [])].filter(([, d]) => d.kind === "image" && d.image).map(([k, d]) => [d.image, k]));
+  const smStems = new Set([...smImages].map(fileStem));
+  const inSm = (p) => {
+    const stem = fileStem(p);
+    return stem.length >= 4 && [...smStems].some((s) => s === stem || s.startsWith(stem));
+  };
+  let unused = 0;
+  const hard = [];
+  for (const p of publicFiles) {
+    if (/logo/i.test(p) || /^(favicon|icon|apple-icon|apple-touch-icon|og|opengraph)/i.test(p.split("/").pop())) continue;
+    const url = `/${p}`;
+    if (declaredImages.has(url)) {
+      add("Photos", "wired", url, `Starting photo of copy key ${declaredImages.get(url)}; Site Manager holds the photo after Sync from Website.`);
+      continue;
+    }
+    const where = findAll(files, containsPattern(url));
+    if (where.length) hard.push({ url, where, matched: inSm(p) });
+    else unused++;
+  }
+  for (const h of hard) add("Photos", "hard_coded", h.url, h.matched ? "Shown from public/, but Site Manager has a photo with the same name. The client's photo changes won't show." : "Shown from public/, so the client can't change it in Site Manager.", "Make it an image copy key (kind: \"image\") or read it from the section it belongs to.", h.where);
+  if (unused) add("Photos", "info", `${unused} files in public/`, "Not named anywhere in the code (used by a CSS file, built at run time, or no longer used).");
+
+  // ---- Site config: facts a config file keeps that Site Manager owns
+  const configFile = (f) => /(^|\/)(config\/[^/]+\.(ts|js|json)|site\.config\.(ts|js)|site\.ts)$/.test(f.rel);
+  const prop = /^\s*(name|siteName|url|siteUrl|baseUrl|phone|officePhone|email|address|hours|indexable|indexing|noindex|robots|social|profiles)\s*:/;
+  for (const f of files.filter(configFile)) {
+    f.lines.forEach((line, i) => {
+      const m = line.match(prop);
+      if (m) add("Site config", "hard_coded", `${f.rel}: ${m[1]}`, "A site fact kept in a config file. Site Manager owns it (Business Info, or Search Listings for indexing), so the site should read it from there.", "Read it from Site Manager and keep the config value only as a fallback, or delete it.", [{ file: f.rel, line: i + 1 }]);
+    });
+  }
+
+  return { site: { name: sm.name, websiteUrl: sm.websiteUrl, modules: [...modules] }, items };
+}
+
+// ---------------------------------------------------------------- the report
+
+export function summarize(items) {
+  const counts = Object.fromEntries(Object.keys(STATUS).map((s) => [s, 0]));
+  for (const i of items) counts[i.status] += i.status === "wired" && /^\d+ copy keys$/.test(i.name) ? Number(i.name.split(" ")[0]) : 1;
+  return { counts, failed: items.some((i) => FAILING.has(i.status)) };
+}
+
+const cell = (s) => String(s ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+
+export function renderReport(result, meta) {
+  const { counts, failed } = summarize(result.items);
+  const out = [];
+  out.push(`# Wiring audit: ${result.site.name}`, "");
+  out.push(`Run ${meta.when} against ${meta.host} (site ${meta.siteId}), site kit ${meta.kitVersion}. Read only.`, "");
+  out.push(failed ? "**Result: not wired.** Fix the Not wired and Missing in Site Manager items below." : "**Result: wired.** Nothing is Not wired or missing in Site Manager.", "");
+  out.push("| Wired | Not wired | Missing in Site Manager | Hard-coded | Unknown |", "| --- | --- | --- | --- | --- |");
+  out.push(`| ${counts.wired} | ${counts.not_wired} | ${counts.missing} | ${counts.hard_coded} | ${counts.unknown} |`, "");
+  out.push("Not wired: Site Manager has it, but editing it changes nothing on the website. Missing in Site Manager: the website uses it, but Site Manager has no such field. Hard-coded: the code keeps its own copy of a Site Manager value. Unknown: the audit couldn't tell.", "");
+  const order = ["not_wired", "missing", "hard_coded", "unknown", "info", "wired"];
+  const areas = [...new Set(result.items.map((i) => i.area))];
+  for (const area of areas) {
+    const rows = result.items.filter((i) => i.area === area && (meta.all || i.status !== "wired" || /^\d+ copy keys$/.test(i.name)));
+    const wiredHidden = result.items.filter((i) => i.area === area && i.status === "wired").length - rows.filter((i) => i.status === "wired").length;
+    out.push(`## ${area}`, "");
+    if (!rows.length && wiredHidden) {
+      out.push(`All ${wiredHidden} wired.`, "");
+      continue;
+    }
+    out.push("| Status | Item | Detail | Fix | Where |", "| --- | --- | --- | --- | --- |");
+    rows.sort((a, b) => order.indexOf(a.status) - order.indexOf(b.status));
+    for (const i of rows) {
+      const where = i.where.map((w) => `${w.file}:${w.line}`).join("<br>") + (i.more ? `<br>and ${i.more} more` : "");
+      out.push(`| ${STATUS[i.status]} | ${cell(i.name)} | ${cell(i.detail)} | ${cell(i.fix ?? "")} | ${where} |`);
+    }
+    if (wiredHidden) out.push("", `Plus ${wiredHidden} wired (run with --all to list them).`);
+    out.push("");
+  }
+  return out.join("\n");
+}
+
+// ---------------------------------------------------------------- command line
+
+function parseArgs(argv) {
+  const a = { dir: process.cwd(), env: [], all: false };
+  for (let i = 0; i < argv.length; i++) {
+    const v = argv[i];
+    if (v === "--dir") a.dir = path.resolve(argv[++i]);
+    else if (v === "--env") a.env.push(argv[++i]);
+    else if (v === "--keys") a.keys = argv[++i];
+    else if (v === "--out") a.out = argv[++i];
+    else if (v === "--all") a.all = true;
+    else if (v === "--upload") a.upload = true;
+    else if (v === "--help" || v === "-h") a.help = true;
+    else throw new Error(`Unknown option ${v}`);
+  }
+  return a;
+}
+
+const HELP = `site-manager-kit audit: checks how this website is wired to Site Manager (it only reads, unless --upload).
+
+  --dir <folder>   the website's folder (default: here)
+  --env <file>     a .env file with BLUEPRINT_URL and BLUEPRINT_API_KEY or BLUEPRINT_AUDIT_KEY (default: .env.local, then .env)
+  --upload         send the result to Site Manager's Wiring tab (needs a Wiring audit key in BLUEPRINT_AUDIT_KEY)
+  --keys <file>    the copy keys file (default: src/copy-keys.ts)
+  --out <file>     where to write the report (default: .wiring/report.md)
+  --all            list wired items too
+
+Exits 1 when anything is Not wired or missing in Site Manager, 2 when the audit (or the upload) couldn't run.`;
+
+export async function main(argv) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (e) {
+    console.error(e.message);
+    console.error(HELP);
+    return 2;
+  }
+  if (args.help) {
+    console.log(HELP);
+    return 0;
+  }
+  const dir = args.dir;
+  const pkg = existsSync(path.join(dir, "package.json")) ? JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8")) : {};
+  const conf = pkg.siteManagerAudit ?? {};
+  const env = {};
+  const envFiles = args.env.length ? args.env : [".env.local", ".env"];
+  for (const f of [...envFiles].reverse()) {
+    const p = path.resolve(dir, f);
+    if (existsSync(p)) Object.assign(env, parseEnv(readFileSync(p, "utf8")));
+  }
+  for (const k of ["BLUEPRINT_URL", "BLUEPRINT_API_KEY", "BLUEPRINT_AUDIT_KEY", "BLUEPRINT_SITE_ID"]) if (process.env[k]) env[k] = process.env[k];
+  // A Wiring audit key reads everything a website key does, so when it's there it's used for both reading and upload.
+  const key = env.BLUEPRINT_AUDIT_KEY || env.BLUEPRINT_API_KEY;
+  const missing = [!env.BLUEPRINT_URL && "BLUEPRINT_URL", !key && "BLUEPRINT_API_KEY (or BLUEPRINT_AUDIT_KEY)"].filter(Boolean);
+  if (missing.length) {
+    console.error(`${missing.join(" and ")} ${missing.length > 1 ? "aren't" : "isn't"} set. Put the site's production values in .env.local (never commit it) or pass --env <file>.`);
+    return 2;
+  }
+  if (args.upload && !env.BLUEPRINT_AUDIT_KEY) {
+    console.error("--upload needs BLUEPRINT_AUDIT_KEY: a Wiring audit key from the site's API Keys tab in Site Manager. Website keys can't upload.");
+    return 2;
+  }
+  const keysFile = args.keys ?? conf.keysFile ?? "src/copy-keys.ts";
+  const siteFiles = readSite(dir, { ignore: conf.ignore ?? [], roots: conf.roots });
+  const routeFiles = ["src/app/api/blueprint/copy-keys/route.ts", "app/api/blueprint/copy-keys/route.ts", "src/app/api/blueprint/copy-keys/route.js", "app/api/blueprint/copy-keys/route.js"];
+  const declaredResult = await loadDeclaredKeys(dir, keysFile);
+  let result;
+  try {
+    result = await audit({ site: siteFiles, api: makeApi(env.BLUEPRINT_URL, key), declaredResult, keysFile, hasCopyKeysRoute: routeFiles.some((f) => existsSync(path.join(dir, f))) });
+  } catch (e) {
+    console.error(`The audit couldn't run: ${e.message}`);
+    return 2;
+  }
+  let kitVersion = "unknown";
+  try {
+    kitVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {}
+  const meta = { when: new Date().toISOString().slice(0, 16).replace("T", " ") + " UTC", host: new URL(env.BLUEPRINT_URL).host, siteId: env.BLUEPRINT_SITE_ID ?? "from the API key", kitVersion, all: args.all };
+  const out = path.resolve(dir, args.out ?? ".wiring/report.md");
+  mkdirSync(path.dirname(out), { recursive: true });
+  if (!args.out) writeFileSync(path.join(dir, ".wiring", ".gitignore"), "*\n");
+  writeFileSync(out, renderReport(result, meta));
+  writeFileSync(out.replace(/\.md$/, "") + ".json", JSON.stringify({ ...meta, ...result }, null, 2));
+  const { counts, failed } = summarize(result.items);
+  console.log(`Wiring audit for ${result.site.name}: ${counts.wired} wired, ${counts.not_wired} not wired, ${counts.missing} missing in Site Manager, ${counts.hard_coded} hard-coded, ${counts.unknown} unknown.`);
+  console.log(`Report: ${path.relative(process.cwd(), out) || out}`);
+  if (args.upload) {
+    const up = await uploadResult(env.BLUEPRINT_URL, env.BLUEPRINT_AUDIT_KEY, result, kitVersion);
+    (up.ok ? console.log : console.error)(up.message);
+    if (!up.ok) return 2;
+  }
+  return failed ? 1 : 0;
+}
+

package/bin/site-manager-kit.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// site-manager-kit's command line. One command so far: `audit` (the wiring audit, audit/wiring-audit.mjs).
+const [command, ...rest] = process.argv.slice(2);
+if (command === "audit") {
+  const { main } = await import("../audit/wiring-audit.mjs");
+  process.exitCode = await main(rest);
+} else {
+  console.log("Usage: site-manager-kit audit [--help]");
+  process.exitCode = command ? 2 : 0;
+}