@analitikisler/ai-tag-debugger 0.8.2 → 0.10.0

package/src/plan-html.js

@@ -0,0 +1,76 @@
+import { CSS, VERSION, escapeHtml, logo, platformLabel } from "./report.js";
+import { LOGOS } from "./brand.js";
+
+const e = escapeHtml;
+const text = (v) => (v === undefined || v === null || v === "" ? `<span class="muted">–</span>` : e(v));
+
+const PLAN_CSS = `
+.pl-event{padding:16px 20px}
+.pl-event+.pl-event{border-top:1px solid var(--border)}
+.pl-head{display:flex;flex-wrap:wrap;align-items:center;gap:8px}
+.pl-head code{font-size:14px}
+.pl-desc{margin:6px 0 10px}
+.pl-trigger{font-size:12px;color:var(--muted);margin-bottom:10px}
+.pl-trigger b{font-weight:500;color:var(--fg)}
+.flag{display:inline-flex;align-items:center;font:500 12px/1 var(--font-sans);padding:4px 8px;border-radius:4px;background:var(--muted-bg);color:var(--muted)}
+.flag.on{background:var(--accent-bg);color:var(--accent-fg)}
+.flag.req{background:var(--warn-bg);color:var(--warn)}
+table.dt td,table.dt th{vertical-align:top}
+`;
+
+const flag = (label, cls = "") => `<span class="flag ${cls}">${e(label)}</span>`;
+
+function paramsTable(event) {
+  const params = Object.entries(event.parameters ?? {});
+  if (!params.length) return `<p class="muted xs">No parameters.</p>`;
+  const required = new Set(event.required_params ?? []);
+  const rows = params
+    .map(([name, p]) => `<tr><td><code>${e(name)}</code>${p?.custom ? ` ${flag("custom")}` : ""}</td><td>${required.has(name) ? flag("required", "req") : `<span class="muted">optional</span>`}</td><td class="mono">${text(p?.example)}</td><td>${text(p?.description)}</td></tr>`)
+    .join("");
+  return `<div class="tscroll"><table class="dt"><thead><tr><th>Parameter</th><th>Required</th><th>Example</th><th>Description</th></tr></thead><tbody>${rows}</tbody></table></div>`;
+}
+
+function eventCard(event) {
+  const trigger = event.trigger ?? {};
+  return `<div class="pl-event">
+<div class="pl-head"><span class="ptag">${e(platformLabel(event.platform ?? "ga4"))}</span><code>${e(event.name)}</code>${flag(event.custom ? "custom event" : "standard event", event.custom ? "on" : "")}</div>
+<p class="pl-desc">${text(event.description)}</p>
+<p class="pl-trigger"><b>Trigger</b> · page: ${text(trigger.page)} · element: ${text(trigger.element)}</p>
+${paramsTable(event)}
+</div>`;
+}
+
+function userPropertiesCard(props) {
+  const body = props.length
+    ? `<div class="tscroll"><table class="dt"><thead><tr><th>Name</th><th>Example</th><th>Description</th></tr></thead><tbody>${props
+        .map((p) => (typeof p === "string" ? { name: p } : p))
+        .map((p) => `<tr><td><code>${e(p.name)}</code></td><td class="mono">${text(p.example)}</td><td>${text(p.description)}</td></tr>`)
+        .join("")}</tbody></table></div>`
+    : `<p class="muted xs">No user properties.</p>`;
+  return `<section class="card"><div class="card-h"><div class="card-t">User properties</div></div><div class="card-c">${body}</div></section>`;
+}
+
+/** A single self-contained, readable page for a measurement plan. Respects branding false like the report. */
+export function renderPlanHtml(plan, { id = "", generatedAt = "", branding = true } = {}) {
+  const events = plan.events ?? [];
+  const custom = events.filter((ev) => ev.custom).length;
+  const title = `Measurement plan${plan.site ? `: ${plan.site}` : ""}`;
+  const meta = [id && `Plan ${id}`, generatedAt, `${events.length} events (${custom} custom)`, `ai-tag-debugger ${VERSION}`].filter(Boolean).join(" · ");
+  const consent = plan.consent_mode ? flag("Consent mode on", "on") : flag("Consent mode off");
+  const footer = branding
+    ? `<div class="wrap"><a href="https://analitikisler.com" class="logo-link" aria-label="analitikisler.com" rel="noopener noreferrer">${logo("stacked", "Analitik İşler", 56, "logo-s")}</a><div><div class="f-links"><a href="https://analitikisler.com" rel="noopener noreferrer">analitikisler.com</a><a href="https://github.com/analitikisler/ai-tag-debugger" rel="noopener noreferrer">GitHub</a></div></div><div class="f-meta">v${VERSION}</div></div>`
+    : `<div class="wrap plain"><div class="f-meta">AI Tag Debugger</div><div class="f-meta">v${VERSION}</div></div>`;
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${e(title)}</title><link rel="icon" type="image/png" href="${LOGOS.favicon}">
+<style>${CSS}${PLAN_CSS}</style></head><body>
+<div class="topbar"><div class="wrap"><span class="product-logo">${logo("atd-lockup", "AI Tag Debugger", 26, "logo-atd")}</span>${branding ? `<a href="https://analitikisler.com" class="byline" rel="noopener noreferrer"><span>by</span>${logo("horizontal", "Analitik İşler", 18, "logo-h")}</a>` : ""}</div></div>
+<header class="wrap title"><div class="eyebrow">Measurement plan</div><h1>${e(title)}</h1><div class="meta">${e(meta)}</div></header>
+<main class="wrap" style="padding-top:24px;padding-bottom:64px"><div class="stack">
+<div>${consent}</div>
+<section class="card"><div class="card-h"><div class="card-t">Events</div><div class="card-d">What should be tracked, where it fires and which parameters it carries.</div></div><div class="card-c tight">${events.length ? events.map(eventCard).join("") : `<p class="muted xs" style="padding:12px">No events.</p>`}</div></section>
+${userPropertiesCard(plan.user_properties ?? [])}
+</div></main>
+<footer class="footer">${footer}</footer>
+</body></html>`;
+}

package/src/plan.js

@@ -0,0 +1,14 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { renderPlanHtml } from "./plan-html.js";
+import { PLAN_FILE, PLAN_HTML_FILE, newPlanDir } from "./workspace.js";
+
+/** Saves a plan (measurement-plan.json and plan.html) in a new aitd/<domain>/plans/<id>/ folder and returns where. */
+export async function savePlan(plan, { dataDir, site, now, branding = true } = {}) {
+  const { id, dir } = await newPlanDir(dataDir, site, now);
+  await mkdir(dir, { recursive: true });
+  const file = path.join(dir, PLAN_FILE);
+  await writeFile(file, `${JSON.stringify(plan, null, 2)}\n`);
+  await writeFile(path.join(dir, PLAN_HTML_FILE), renderPlanHtml(plan, { id, generatedAt: (now ?? new Date()).toISOString().slice(0, 16).replace("T", " "), branding }));
+  return { id, dir, file };
+}

package/src/providers.js

@@ -28,7 +28,7 @@ export function resolveProviderName(name, env = process.env) {
   return "anthropic";
 }
 
-const NO_API_KEY = `No AI provider key found. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY (or OPENAI_COMPATIBLE_BASE_URL for an OpenAI-compatible API), or pick one with --provider. To run without any AI model, replay the fixed steps with --scripted --no-ai.`;
+const NO_API_KEY = `No AI provider key found. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY (or OPENAI_COMPATIBLE_BASE_URL for an OpenAI-compatible API), or pick one with --provider. To run without any AI model, replay saved steps with --no-ai.`;
 
 function hasApiKey(env) {
   return Boolean(env.OPENAI_COMPATIBLE_BASE_URL || env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN || env.OPENAI_API_KEY || env.GEMINI_API_KEY || env.GOOGLE_API_KEY);

package/src/replay.js

@@ -24,6 +24,53 @@ export function replayableJourney(run) {
   };
 }
 
+/**
+ * Writes the steps each journey took into journeys[].steps of a config file, so a later
+ * --scripted --no-ai run repeats them without an AI model. Creates the file when it doesn't exist.
+ * A journey run on several viewports keeps the steps of its first one. Journeys that took no
+ * repeatable steps are left as they were. A config with no plan gets the run's, so ready-made
+ * journeys keep their expected events.
+ * @returns {Promise<{ saved: string[], skipped: string[] }>}
+ */
+export async function writeSavedSteps(file, { site, plan, journeys, runs }) {
+  let config = {};
+  const text = await readFile(file, "utf8").catch((err) => {
+    if (err.code === "ENOENT") return null;
+    throw new Error(`Could not read ${file}: ${err.message}`);
+  });
+  if (text !== null) {
+    try {
+      config = JSON.parse(text);
+    } catch (err) {
+      throw new Error(`Could not read ${file}: ${err.message}`);
+    }
+  }
+  config.site ??= site;
+  if (config.plan === undefined && plan?.events?.length) config.plan = plan;
+  const list = [...(config.journeys ?? [])];
+  const saved = [];
+  const skipped = [];
+  for (const journey of journeys) {
+    const run = runs.find((r) => r.journeyId === journey.id);
+    const { viewport: _v, ...steps } = run ? replayableJourney(run) : { steps: [] };
+    if (!steps.steps.length && !steps.start) {
+      skipped.push(journey.id);
+      continue;
+    }
+    const i = list.findIndex((j) => j.id === journey.id);
+    const { start: _s, steps: _st, incomplete: _in, ...kept } = i === -1 ? { id: journey.id, ...(journey.goal ? { goal: journey.goal } : {}) } : list[i];
+    const entry = { ...kept, ...steps, id: journey.id };
+    if (i === -1) list.push(entry);
+    else list[i] = entry;
+    saved.push(journey.id);
+  }
+  if (saved.length) {
+    await mkdir(path.dirname(path.resolve(file)), { recursive: true });
+    await writeFile(file, `${JSON.stringify({ ...config, journeys: list }, null, 2)}\n`);
+  }
+  return { saved, skipped };
+}
+
 /** One line per finding, sorted: what a replay is compared on. */
 export function findingKeys(findings) {
   return findings.map((f) => [f.severity, f.check, f.journey, f.viewport, f.platform ?? "-", f.event ?? "-"].join(" ")).sort();

package/src/report.js

@@ -6,7 +6,7 @@ import { decodeGa4Item, isEventParam, paramTip } from "./glossary.js";
 import { LOGOS } from "./brand.js";
 import { readFileSync } from "node:fs";
 
-const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
 const EXPLAIN_SYSTEM = `You are a senior digital analytics consultant reviewing an automated tracking audit. You receive findings from deterministic checks, the measurement plan, the hits captured on each step of each journey, and optionally a Google Tag Manager container export.
 
@@ -120,7 +120,7 @@ export async function explainFindings({ findings, plan, runs, gtmContainer, prov
   }
 }
 
-const escapeHtml = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export const escapeHtml = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 
 function attachExplanations(findings, explained) {
   const byIndex = new Map((explained?.explanations ?? []).map((e) => [e.finding, e]));
@@ -149,11 +149,12 @@ const formatPush = (value) => (isConsentEntry(value) ? `gtag(${value.map((v) =>
 const mdText = (v) => String(v ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 const mdCode = (v) => String(v ?? "").replace(/`/g, "'").replace(/\n/g, " ");
 
-export function renderMarkdown({ title, generatedAt, findings, explained, runs, lang = "en", branding = true }) {
+export function renderMarkdown({ title, generatedAt, findings, explained, runs, lang = "en", branding = true, against = null, planCheck = null }) {
   const m = messages(lang);
   const rows = attachExplanations(findings, explained);
   const counts = summarize(rows);
-  const lines = [`# ${mdText(title)}`, "", m.ui.generated(generatedAt), "", `**${m.ui.counts(counts)}**`, ""];
+  const lines = [`# ${mdText(title)}`, "", m.ui.generated(generatedAt), "", ...(against ? [mdText(m.ui.checkedAgainst(against)), ""] : []), `**${m.ui.counts(counts)}**`, ""];
+  if (planCheck) lines.push(...planVsSiteMd(m, planCheck));
   const sum = summaryParts(explained?.summary);
   if (sum) {
     lines.push(`## ${m.ui.summary}`, "", sum.text ? mdText(sum.text) : `**${mdText(sum.headline)}**`, "");
@@ -193,7 +194,7 @@ export function renderMarkdown({ title, generatedAt, findings, explained, runs,
 }
 
 const PLATFORM_ORDER = ["ga4", "google_ads", "meta", "tiktok", "x", "pinterest", "snapchat", "klaviyo", "hotjar"];
-const platformLabel = (p) => PROVIDERS[p] ?? String(p).replace(/[_-]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+export const platformLabel = (p) => PROVIDERS[p] ?? String(p).replace(/[_-]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 const platformRank = (p) => (PLATFORM_ORDER.includes(p) ? PLATFORM_ORDER.indexOf(p) : PLATFORM_ORDER.length);
 
 // Pixel event names and their GA4 / dataLayer counterparts, so a Meta or TikTok hit can be shown next to the push behind it.
@@ -455,7 +456,7 @@ const sevIcon = (sev) => ICON[sev === "broken" ? "broken" : sev === "info" ? "in
 const sec = (name, label) => `<div class="sec-h">${ic(ICON[name], 14)}<span>${label}</span></div>`;
 const badge = (sev, text) => `<span class="badge ${sev}">${escapeHtml(text)}</span>`;
 /** A logo with its light and dark versions, switched by the viewer's color scheme. */
-const logo = (key, alt, height, cls) => `<picture class="${cls}"><source media="(prefers-color-scheme: dark)" srcset="${LOGOS[`${key}-dark`]}"><img src="${LOGOS[`${key}-light`]}" alt="${alt}" height="${height}"></picture>`;
+export const logo = (key, alt, height, cls) => `<picture class="${cls}"><source media="(prefers-color-scheme: dark)" srcset="${LOGOS[`${key}-dark`]}"><img src="${LOGOS[`${key}-light`]}" alt="${alt}" height="${height}"></picture>`;
 
 /** The journey and step a finding's place points at. Steps are named by label; when labels repeat, prefer the step where the finding's event fired. */
 function whereTarget(runs, w, f) {
@@ -610,6 +611,29 @@ ${provs.length ? `<div class="card"><div class="card-h"><div class="card-t">${m.
 }
 
 /** Each planned event × each journey: sent, not sent, or not expected there (or its provider not checked). */
+const BUCKET_SEV = { implemented: "ok", missing: "broken", missing_params: "broken", wrong_values: "warning", unplanned: "info", not_checked: "muted" };
+const coverageLines = (m, pc) => [
+  m.ui.coverageLine(pc.coverage),
+  ...sortPlatforms(Object.keys(pc.coverage.platforms)).map((p) => `${platformLabel(p)}: ${m.ui.coverageLine(pc.coverage.platforms[p])}`),
+];
+const pcSort = (pc) => [...pc.events].sort((a, b) => BUCKET_ORDER.indexOf(a.bucket) - BUCKET_ORDER.indexOf(b.bucket) || platformRank(a.platform) - platformRank(b.platform));
+const BUCKET_ORDER = ["missing", "missing_params", "wrong_values", "implemented", "unplanned", "not_checked"];
+
+function planVsSiteMd(m, pc) {
+  const [overall, ...perPlatform] = coverageLines(m, pc);
+  const lines = [`## ${m.ui.planVsSite}`, "", `**${mdText(overall)}**`, "", ...perPlatform.map((l) => `- ${mdText(l)}`), ...(perPlatform.length ? [""] : [])];
+  lines.push(`| ${m.ui.event} | ${m.ui.bucketCol} | |`, "|---|---|---|");
+  for (const e of pcSort(pc)) lines.push(`| ${mdText(platformLabel(e.platform))} \`${mdCode(e.event)}\` | ${m.ui.bucket[e.bucket]} | ${mdText((e.details ?? []).join(" ")).replace(/\|/g, "\\|")} |`);
+  lines.push("");
+  return lines;
+}
+
+function planVsSiteCard(m, pc) {
+  const [overall, ...perPlatform] = coverageLines(m, pc);
+  const rows = pcSort(pc).map((e) => `<tr><td><span class="ptag p-${safeKey(e.platform)}">${escapeHtml(platformLabel(e.platform))}</span> <code>${escapeHtml(e.event)}</code></td><td>${badge(BUCKET_SEV[e.bucket], m.ui.bucket[e.bucket])}</td><td class="muted xs">${(e.details ?? []).map(detailHtml).join("<br>")}</td></tr>`).join("");
+  return `<div class="card" id="plan-vs-site"><div class="card-h"><div class="card-t">${m.ui.planVsSite}</div><div class="card-d">${m.ui.planVsSiteLead}</div></div><div class="card-c"><p><strong>${escapeHtml(overall)}</strong></p>${perPlatform.length ? `<p class="muted xs">${perPlatform.map(escapeHtml).join("<br>")}</p>` : ""}<div class="tscroll"><table class="dt"><thead><tr><th>${m.ui.event}</th><th>${m.ui.bucketCol}</th><th></th></tr></thead><tbody>${rows}</tbody></table></div></div></div>`;
+}
+
 function coverageCard(m, plan, runs) {
   const head = `<div class="card-h"><div class="card-t">${m.ui.planCoverage}</div><div class="card-d">${m.ui.planCoverageLead}</div></div>`;
   if (!plan?.events?.length || !runs.length) return `<div class="card">${head}<div class="card-c"><p class="muted">${m.ui.noPlan}</p></div></div>`;
@@ -679,7 +703,7 @@ function navCss(runs) {
   return out.join("\n");
 }
 
-const CSS = `
+export const CSS = `
 :root{
 --bg:#FFFFFF;--page:#F7F9FC;--fg:#0A0E1A;--muted:#5A6480;--muted-bg:#F1F4F9;--border:#E3E7EF;--input:#E3E7EF;
 --accent:#4F8EF7;--accent-fg:#2F6FDB;--accent-bg:#EBF1FE;--orange:#FF6D33;
@@ -916,7 +940,7 @@ pre{margin:8px 0 0;font-size:12px;line-height:1.5;background:var(--muted-bg);bor
 @media print{.toptabs,.jtabs,.stepnav,.filter>label,.filter>input,.tabs.seg>label,.sevfilter{display:none}.tabpanel,.jpanel,.sdetail,.tabs.seg>.panel{display:block!important}.jpanel{margin-bottom:32px}.sdetail{margin-bottom:16px;break-inside:avoid-page}details>*{display:block}}
 `;
 
-export function renderHtml({ title, generatedAt, findings, explained, runs, plan = null, lang = "en", branding = true }) {
+export function renderHtml({ title, generatedAt, findings, explained, runs, plan = null, lang = "en", branding = true, against = null, planCheck = null }) {
   const m = messages(lang);
   const rows = attachExplanations(findings, explained);
   const counts = summarize(rows);
@@ -938,12 +962,12 @@ ${navCss(runs)}</style></head><body>
 <header class="wrap title">
 <div class="eyebrow">${m.ui.eyebrow}</div>
 <h1>${escapeHtml(title)}</h1>
-<div class="meta">${escapeHtml(generatedAt)} · ${escapeHtml(m.ui.headerMeta(runs.length, checkedProviders(runs).length))} · ai-tag-debugger ${VERSION}</div>
+<div class="meta">${escapeHtml(generatedAt)} · ${escapeHtml(m.ui.headerMeta(runs.length, checkedProviders(runs).length))} · ai-tag-debugger ${VERSION}</div>${against ? `\n<div class="meta">${escapeHtml(m.ui.checkedAgainst(against))}</div>` : ""}
 </header>
 <nav class="toptabs" aria-label="${m.ui.sections}"><div class="wrap">
 <a href="#overview">${m.ui.tabOverview}</a><a href="#findings">${m.ui.findings} <span class="n">${problems}</span></a><a href="#journeys">${m.ui.tabJourneys} <span class="n">${runs.length}</span></a><a href="#scope">${m.ui.tabScope}</a></div></nav>
 <main class="wrap">
-<section class="tabpanel" id="overview" aria-label="${m.ui.tabOverview}">${overviewTab(m, findings, rows, counts, explained, runs)}</section>
+<section class="tabpanel" id="overview" aria-label="${m.ui.tabOverview}">${planCheck ? planVsSiteCard(m, planCheck) : ""}${overviewTab(m, findings, rows, counts, explained, runs)}</section>
 <section class="tabpanel" id="findings" aria-label="${m.ui.findings}">${findingsTab(m, runs, rows)}</section>
 <section class="tabpanel" id="journeys" aria-label="${m.ui.tabJourneys}">${journeysTab(m, lang, findings, runs, flagged)}</section>
 <section class="tabpanel" id="scope" aria-label="${m.ui.tabScope}"><div class="stack">${coverageCard(m, plan, runs)}${providersCard(m, runs)}</div></section>

package/src/sheet.js

@@ -0,0 +1,321 @@
+// Plan import and export as a spreadsheet: one row per event parameter on an "events" tab and
+// one row per user property on a "user_properties" tab. CSV needs nothing extra; .xlsx uses the
+// optional fflate package (zip), loaded only when an .xlsx file is read or written.
+import { readFile, writeFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { PROVIDERS as PLATFORMS } from "./parsers.js";
+
+export const EVENT_COLUMNS = ["event", "platform", "parameter", "required", "example", "trigger", "description"];
+// Optional columns that keep the rest of a plan on a round trip.
+export const EXTRA_EVENT_COLUMNS = ["custom", "journeys"];
+export const USER_PROPERTY_COLUMNS = ["name", "description", "example"];
+const TRIGGER_SEP = " > ";
+
+// ---------- plan <-> rows ----------
+
+const yesNo = (v) => (v ? "yes" : "no");
+
+/** The plan as the two tabs' rows: { events: object[], user_properties: object[] }. */
+export function planToRows(plan) {
+  const events = [];
+  for (const ev of plan.events ?? []) {
+    const trigger = ev.trigger ? [ev.trigger.page, ev.trigger.element].filter(Boolean).join(TRIGGER_SEP) : "";
+    const params = { ...(ev.parameters ?? {}) };
+    for (const p of ev.required_params ?? []) params[p] ??= {};
+    const required = new Set(ev.required_params ?? []);
+    const base = { event: ev.name, platform: ev.platform ?? "ga4", custom: ev.custom ? "yes" : "", journeys: (ev.journeys ?? []).join(", ") };
+    const names = Object.keys(params);
+    // An event row (empty parameter) carries the event's own description; it is left out when the
+    // event has parameters and nothing to say.
+    if (!names.length || ev.description) events.push({ ...base, parameter: "", required: "", example: "", trigger, description: ev.description ?? "" });
+    for (const name of names) {
+      const p = params[name] ?? {};
+      events.push({
+        ...base,
+        parameter: name,
+        required: yesNo(required.has(name)),
+        example: p.example ?? "",
+        trigger,
+        description: p.description ?? "",
+        custom: [ev.custom ? "event" : "", p.custom ? "parameter" : ""].filter(Boolean).join(", "),
+      });
+    }
+  }
+  const user_properties = (plan.user_properties ?? []).map((u) => ({ name: u.name, description: u.description ?? "", example: u.example ?? "" }));
+  return { events, user_properties };
+}
+
+const fail = (msg) => {
+  const err = new Error(msg);
+  err.sheetError = true;
+  return err;
+};
+
+function headerOf(tab, rows, needed, optional, warnings) {
+  if (!rows.length) throw fail(`${tab}: the tab is empty. Its first row must name the columns: ${needed.join(", ")}.`);
+  const header = rows[0].map((h) => String(h ?? "").trim().toLowerCase());
+  const missing = needed.filter((c) => !header.includes(c) && !(c === "description" && tab === "events"));
+  if (missing.length) throw fail(`${tab}, row 1: missing column${missing.length > 1 ? "s" : ""} ${missing.map((c) => `"${c}"`).join(", ")}. The first row must name the columns: ${needed.join(", ")}.`);
+  const unknown = header.filter((h) => h && !needed.includes(h) && !optional.includes(h));
+  for (const h of unknown) warnings.push(`${tab}: column "${h}" is not used and was ignored.`);
+  return header;
+}
+
+function records(rows, header) {
+  return rows.slice(1).map((cells, i) => {
+    const rec = { row: i + 2 };
+    header.forEach((h, j) => {
+      if (h) rec[h] = String(cells[j] ?? "").trim();
+    });
+    return rec;
+  }).filter((r) => header.some((h) => h && r[h]));
+}
+
+/**
+ * Builds a plan from the two tabs' rows (arrays of cell arrays, header first).
+ * Returns { plan, warnings }. Throws an error naming the tab, row and fix.
+ */
+export function rowsToPlan({ events: eventRows = [], user_properties: upRows = null }, { site } = {}) {
+  const warnings = [];
+  const header = headerOf("events", eventRows, EVENT_COLUMNS, EXTRA_EVENT_COLUMNS, warnings);
+  const byKey = new Map();
+  for (const r of records(eventRows, header)) {
+    const at = `events, row ${r.row}`;
+    if (!r.event) throw fail(`${at}: "event" is empty. Give the event name, e.g. purchase.`);
+    const platform = (r.platform || "ga4").toLowerCase();
+    if (!PLATFORMS[platform]) throw fail(`${at}: "platform" must be one of ${Object.keys(PLATFORMS).join(", ")} (found "${r.platform}").`);
+    const required = (r.required ?? "").toLowerCase();
+    if (!["yes", "no", ""].includes(required)) throw fail(`${at}: "required" must be yes or no (found "${r.required}").`);
+    if (required && !r.parameter) throw fail(`${at}: "required" is set but "parameter" is empty. Name the parameter, or leave "required" empty on the event's own row.`);
+    const custom = (r.custom ?? "").toLowerCase().split(",").map((s) => s.trim()).filter(Boolean);
+    const okCustom = ["yes", "no", "event", "parameter"];
+    const bad = custom.find((c) => !okCustom.includes(c));
+    if (bad) throw fail(`${at}: "custom" must be yes, no, event or parameter (found "${r.custom}").`);
+
+    const key = `${platform}:${r.event}`;
+    let ev = byKey.get(key);
+    if (!ev) {
+      ev = { platform, name: r.event, parameters: {}, required_params: [] };
+      byKey.set(key, ev);
+    }
+    if (custom.includes("event") || (!r.parameter && custom.includes("yes"))) ev.custom = true;
+    if (r.trigger && !ev.trigger) {
+      const [page, ...rest] = r.trigger.split(TRIGGER_SEP);
+      ev.trigger = { page: page.trim(), ...(rest.length ? { element: rest.join(TRIGGER_SEP).trim() } : {}) };
+    }
+    if (r.journeys && !ev.journeys) ev.journeys = r.journeys.split(",").map((s) => s.trim()).filter(Boolean);
+    if (!r.parameter) {
+      if (r.description) ev.description = r.description;
+      continue;
+    }
+    if (ev.parameters[r.parameter]) throw fail(`${at}: parameter "${r.parameter}" of ${r.event} is listed twice. Keep one row per parameter.`);
+    ev.parameters[r.parameter] = {
+      ...(custom.includes("parameter") || custom.includes("yes") ? { custom: true } : {}),
+      ...(r.description ? { description: r.description } : {}),
+      ...(r.example ? { example: r.example } : {}),
+    };
+    if (required === "yes") ev.required_params.push(r.parameter);
+  }
+  if (!byKey.size) throw fail("events: no events found. Add one row per event parameter below the column names.");
+
+  const events = [...byKey.values()].map(({ platform, name, custom, description, trigger, journeys, required_params, parameters }) => ({
+    platform,
+    name,
+    ...(custom ? { custom: true } : {}),
+    ...(description ? { description } : {}),
+    ...(trigger ? { trigger } : {}),
+    ...(journeys ? { journeys } : {}),
+    ...(required_params.length ? { required_params } : {}),
+    ...(Object.keys(parameters).length ? { parameters } : {}),
+  }));
+
+  const user_properties = [];
+  if (upRows) {
+    const upHeader = headerOf("user_properties", upRows, USER_PROPERTY_COLUMNS, [], warnings);
+    const seen = new Set();
+    for (const r of records(upRows, upHeader)) {
+      if (!r.name) throw fail(`user_properties, row ${r.row}: "name" is empty. Give the user property name, e.g. customer_type.`);
+      if (seen.has(r.name)) throw fail(`user_properties, row ${r.row}: "${r.name}" is listed twice. Keep one row per user property.`);
+      seen.add(r.name);
+      user_properties.push({ name: r.name, description: r.description ?? "", example: r.example ?? "" });
+    }
+  }
+  return { plan: { ...(site ? { site } : {}), consent_mode: true, events, user_properties }, warnings };
+}
+
+const toCells = (objs, columns) => [columns, ...objs.map((o) => columns.map((c) => o[c] ?? ""))];
+
+// ---------- CSV ----------
+
+const csvCell = (v) => {
+  const s = String(v ?? "");
+  return /[",\r\n]/.test(s) || /^\s|\s$/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+};
+export const toCsv = (rows) => `${rows.map((r) => r.map(csvCell).join(",")).join("\r\n")}\r\n`;
+
+/** Parses CSV text (RFC 4180, comma or semicolon separated) into an array of cell arrays. */
+export function parseCsv(text) {
+  text = text.replace(/^/, "");
+  const firstLine = text.slice(0, text.search(/\r?\n|$/));
+  const sep = (firstLine.match(/;/g)?.length ?? 0) > (firstLine.match(/,/g)?.length ?? 0) ? ";" : ",";
+  const rows = [];
+  let row = [];
+  let cell = "";
+  let quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch === '"' && text[i + 1] === '"') {
+        cell += '"';
+        i++;
+      } else if (ch === '"') quoted = false;
+      else cell += ch;
+    } else if (ch === '"') quoted = true;
+    else if (ch === sep) {
+      row.push(cell);
+      cell = "";
+    } else if (ch === "\n" || ch === "\r") {
+      if (ch === "\r" && text[i + 1] === "\n") i++;
+      row.push(cell);
+      rows.push(row);
+      row = [];
+      cell = "";
+    } else cell += ch;
+  }
+  if (cell || row.length) {
+    row.push(cell);
+    rows.push(row);
+  }
+  return rows;
+}
+
+// ---------- XLSX (minimal: inline strings out, shared or inline strings and numbers in) ----------
+
+async function loadFflate() {
+  try {
+    return await import("fflate");
+  } catch {
+    throw new Error('Reading and writing .xlsx files needs the optional "fflate" package, which is not installed. Install it with: npm install fflate (or use CSV: --format csv for export, a .csv file for import).');
+  }
+}
+
+const xmlEscape = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, "");
+const xmlUnescape = (s) => s.replace(/&(lt|gt|quot|apos|amp|#\d+|#x[0-9a-f]+);/gi, (_, e) => {
+  const named = { lt: "<", gt: ">", quot: '"', apos: "'", amp: "&" }[e.toLowerCase()];
+  if (named) return named;
+  return String.fromCodePoint(e[1].toLowerCase() === "x" ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10));
+});
+const colName = (i) => (i >= 26 ? colName(Math.floor(i / 26) - 1) : "") + String.fromCharCode(65 + (i % 26));
+const colIndex = (letters) => [...letters].reduce((n, c) => n * 26 + c.charCodeAt(0) - 64, 0) - 1;
+
+function sheetXml(rows) {
+  const body = rows.map((r, i) => `<row r="${i + 1}">${r.map((v, j) => (v === "" || v == null ? "" : `<c r="${colName(j)}${i + 1}" t="inlineStr"${i === 0 ? ' s="1"' : ""}><is><t xml:space="preserve">${xmlEscape(v)}</t></is></c>`)).join("")}</row>`).join("");
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><sheetViews><sheetView workbookViewId="0"><pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/></sheetView></sheetViews><sheetData>${body}</sheetData></worksheet>`;
+}
+
+/** An .xlsx file (Uint8Array) with one sheet per entry of { name: rows }. */
+export async function writeXlsx(sheets) {
+  const { zipSync, strToU8 } = await loadFflate();
+  const names = Object.keys(sheets);
+  const files = {
+    "[Content_Types].xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/><Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>${names.map((_, i) => `<Override PartName="/xl/worksheets/sheet${i + 1}.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>`).join("")}</Types>`,
+    "_rels/.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/></Relationships>`,
+    "xl/workbook.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><sheets>${names.map((n, i) => `<sheet name="${xmlEscape(n)}" sheetId="${i + 1}" r:id="rId${i + 1}"/>`).join("")}</sheets></workbook>`,
+    "xl/_rels/workbook.xml.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">${names.map((_, i) => `<Relationship Id="rId${i + 1}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet${i + 1}.xml"/>`).join("")}<Relationship Id="rId${names.length + 1}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/></Relationships>`,
+    "xl/styles.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><fonts count="2"><font><sz val="11"/><name val="Calibri"/></font><font><b/><sz val="11"/><name val="Calibri"/></font></fonts><fills count="2"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill></fills><borders count="1"><border/></borders><cellStyleXfs count="1"><xf/></cellStyleXfs><cellXfs count="2"><xf/><xf fontId="1" applyFont="1"/></cellXfs></styleSheet>`,
+  };
+  names.forEach((n, i) => (files[`xl/worksheets/sheet${i + 1}.xml`] = sheetXml(sheets[n])));
+  return zipSync(Object.fromEntries(Object.entries(files).map(([k, v]) => [k, strToU8(v)])));
+}
+
+const textOf = (xml) => [...xml.matchAll(/<t(?:\s[^>]*)?>([\s\S]*?)<\/t>|<t(?:\s[^>]*)?\/>/g)].map((m) => xmlUnescape(m[1] ?? "")).join("");
+
+/** Reads an .xlsx file's sheets as { name: rows } (rows are arrays of cell text). */
+export async function readXlsx(bytes) {
+  const { unzipSync, strFromU8 } = await loadFflate();
+  let zip;
+  try {
+    zip = unzipSync(bytes);
+  } catch {
+    throw new Error("This is not a readable .xlsx file. Save it as an Excel workbook (.xlsx) or as CSV.");
+  }
+  const get = (p) => (zip[p] ? strFromU8(zip[p]) : null);
+  const workbook = get("xl/workbook.xml");
+  if (!workbook) throw new Error("This is not a readable .xlsx file. Save it as an Excel workbook (.xlsx) or as CSV.");
+  const rels = Object.fromEntries([...(get("xl/_rels/workbook.xml.rels") ?? "").matchAll(/<Relationship\b[^>]*>/g)].map((m) => [m[0].match(/Id="([^"]+)"/)?.[1], m[0].match(/Target="([^"]+)"/)?.[1]]));
+  const shared = [...(get("xl/sharedStrings.xml") ?? "").matchAll(/<si>([\s\S]*?)<\/si>/g)].map((m) => textOf(m[1].replace(/<rPh\b[\s\S]*?<\/rPh>/g, "")));
+  const sheets = {};
+  for (const m of workbook.matchAll(/<sheet\b[^>]*>/g)) {
+    const name = xmlUnescape(m[0].match(/name="([^"]*)"/)?.[1] ?? "");
+    const target = rels[m[0].match(/r:id="([^"]+)"/)?.[1]];
+    if (!target) continue;
+    const file = target.startsWith("/") ? target.slice(1) : path.posix.normalize(`xl/${target}`);
+    const xml = get(file) ?? "";
+    const rows = [];
+    for (const r of xml.matchAll(/<row\b([^>]*?)(?:\/>|>([\s\S]*?)<\/row>)/g)) {
+      const rowNum = Number(r[1].match(/r="(\d+)"/)?.[1] ?? rows.length + 1);
+      const cells = [];
+      for (const c of (r[2] ?? "").matchAll(/<c\b([^>]*?)(?:\/>|>([\s\S]*?)<\/c>)/g)) {
+        const ref = c[1].match(/r="([A-Z]+)\d+"/)?.[1];
+        const type = c[1].match(/t="([^"]+)"/)?.[1];
+        const inner = c[2] ?? "";
+        const v = inner.match(/<v>([\s\S]*?)<\/v>/)?.[1];
+        let value = "";
+        if (type === "s") value = shared[Number(v)] ?? "";
+        else if (type === "inlineStr") value = textOf(inner.match(/<is>([\s\S]*?)<\/is>/)?.[1] ?? "");
+        else if (type === "b") value = v === "1" ? "TRUE" : "FALSE";
+        else if (v != null) value = xmlUnescape(v);
+        cells[ref ? colIndex(ref) : cells.length] = value;
+      }
+      rows[rowNum - 1] = Array.from(cells, (x) => x ?? "");
+    }
+    sheets[name] = Array.from(rows, (x) => x ?? []);
+  }
+  return sheets;
+}
+
+// ---------- files ----------
+
+const exists = (p) => stat(p).then(() => true, () => false);
+
+/** Reads a plan spreadsheet (.xlsx, or events.csv with an optional user_properties.csv beside it). */
+export async function readPlanSheet(file, { site } = {}) {
+  const ext = path.extname(file).toLowerCase();
+  if (!(await exists(file))) throw new Error(`No file at ${file}.`);
+  let tabs;
+  if (ext === ".xlsx") {
+    const sheets = await readXlsx(await readFile(file));
+    const find = (n) => Object.entries(sheets).find(([k]) => k.trim().toLowerCase() === n)?.[1];
+    const events = find("events");
+    if (!events) throw new Error(`${path.basename(file)} has no tab named "events" (found ${Object.keys(sheets).map((k) => `"${k}"`).join(", ") || "none"}). Rename the tab with the events to "events".`);
+    tabs = { events, user_properties: find("user_properties") ?? null };
+  } else if (ext === ".csv") {
+    const upFile = path.join(path.dirname(file), "user_properties.csv");
+    const isUp = path.basename(file).toLowerCase() === "user_properties.csv";
+    if (isUp) throw new Error(`Import the events file (events.csv); ${path.basename(file)} beside it is read too.`);
+    tabs = { events: parseCsv(await readFile(file, "utf8")), user_properties: (await exists(upFile)) ? parseCsv(await readFile(upFile, "utf8")) : null };
+  } else {
+    throw new Error(`Import a .xlsx or .csv file (got ${path.basename(file)}).`);
+  }
+  const result = rowsToPlan(tabs, { site });
+  if (!tabs.user_properties) result.warnings.push(ext === ".csv" ? "No user_properties.csv beside the file, so the plan has no user properties." : 'No "user_properties" tab, so the plan has no user properties.');
+  return result;
+}
+
+/** Writes a plan as plan.xlsx (or events.csv and user_properties.csv) in dir; returns the files written. */
+export async function writePlanSheet(plan, dir, { format = "xlsx" } = {}) {
+  const { events, user_properties } = planToRows(plan);
+  const hasExtra = (c) => events.some((r) => r[c]);
+  const eventColumns = [...EVENT_COLUMNS, ...EXTRA_EVENT_COLUMNS.filter(hasExtra)];
+  const tabs = { events: toCells(events, eventColumns), user_properties: toCells(user_properties, USER_PROPERTY_COLUMNS) };
+  if (format === "csv") {
+    const files = [path.join(dir, "events.csv"), path.join(dir, "user_properties.csv")];
+    await writeFile(files[0], `${toCsv(tabs.events)}`);
+    await writeFile(files[1], `${toCsv(tabs.user_properties)}`);
+    return files;
+  }
+  if (format !== "xlsx") throw new Error(`--format must be xlsx or csv (found "${format}").`);
+  const file = path.join(dir, "plan.xlsx");
+  await writeFile(file, await writeXlsx(tabs));
+  return [file];
+}