@analitikisler/ai-tag-debugger 0.9.0 → 0.10.0

package/src/help.js

@@ -0,0 +1,104 @@
+import { LANGUAGES } from "./i18n.js";
+import { PROVIDERS } from "./providers.js";
+import { JOURNEY_PRESETS } from "./journeys.js";
+
+const journeys = Object.keys(JOURNEY_PRESETS).join(", ");
+
+const MAIN = `aitd: an open-source AI agent that QA-tests your analytics and ad tracking.
+
+Usage: aitd <command> [options]
+
+Commands:
+  plan     Draft a measurement plan: what should be tracked
+  run      Audit what a site actually sends, and compare it to a plan
+  replay   Re-check saved sites offline, without AI
+  mcp      Start the MCP server for Claude, ChatGPT and other chat apps
+
+Examples:
+  aitd plan --site https://example.com
+  aitd run --site https://example.com --against latest
+  aitd run --site https://example.com --journey purchase
+
+Run "aitd <command> --help" for that command's options.   -h, --help   -v, --version`;
+
+const RUN = `Usage: aitd run --site <url> (--against <plan> | --journey <id> | --goal "<text>")
+
+Audit what a site actually sends while an AI agent walks its journeys. Needs an AI key
+(${Object.values(PROVIDERS).map((p) => p.env).join(", ")}) unless --no-ai.
+
+What to test (at least one):
+  --against <plan>     Check against a plan: latest, first, a plan ID or a plan file or folder
+  --journey <id>       A ready-made journey: ${journeys} (repeatable)
+  --goal "<text>"      A journey in plain language (repeatable)
+
+Options:
+  --site <url>         The site to audit
+  --config <file>      Take the site and journeys from a config file
+  --events <names>     Only check these events, e.g. purchase,add_to_cart
+  --lang <code>        Report language: ${Object.keys(LANGUAGES).join(" or ")}
+  --headed             Show the browser window
+  --fail-on <level>    Exit 1 at this level: broken (default), risk, warning, never
+
+AI:  --provider <name>   --model <id>   (default: whichever API key is set)
+
+Advanced:
+  --max-steps <n>   --platforms <list>   --viewport <name>   --data-dir <dir>
+  --scripted   --no-ai   --save-site <dir>   --save-steps <file>   (see the README)`;
+
+const PLAN = `Usage: aitd plan --site <url>
+       aitd plan list --site <url>
+       aitd plan import <file> --site <url>
+       aitd plan export <plan> --site <url>
+
+Draft a measurement plan: what should be tracked. The AI explores one page of each type
+and proposes events, parameters and user properties. Plans are saved in
+aitd/<domain>/plans/<id>/. Needs an AI key (${Object.values(PROVIDERS).map((p) => p.env).join(", ")}).
+
+Commands:
+  (none)               Draft a new plan from the site
+  list                 List the site's plan IDs, oldest first
+  import <file>        Save a plan from a spreadsheet (xlsx or csv) as a new plan
+  export <plan>        Write a plan to a spreadsheet to edit; <plan> is latest, first, an ID or a path
+
+Options:
+  --site <url>         The site (required)
+  --headed             Show the browser window
+
+AI:  --provider <name>   --model <id>   (default: whichever API key is set)
+
+Advanced:
+  --max-steps <n>   --data-dir <dir>   --format <xlsx|csv>   (see the README)`;
+
+const REPLAY = `Usage: aitd replay <dir>... [--update]
+
+Audit sites saved with "aitd run --save-site <dir>" again, offline and without AI, and
+list findings that changed. Exits with code 1 when any did.
+
+Options:
+  --update             Make this replay's findings the expected ones (check the changes first)
+
+Advanced:
+  --out <dir>          Where to write the reports (default: <dir>/last-replay)`;
+
+const MCP = `Usage: aitd mcp [--http] [--port <n>]
+
+Start the MCP server for Claude, ChatGPT, Gemini and other chat apps. It talks over
+stdio unless you pass --http.
+
+Options:
+  --http               Serve over Streamable HTTP, for apps that connect to a URL
+  --port <n>           HTTP port (default 8787)
+
+Advanced:
+  --host <addr>        HTTP host (default 127.0.0.1)
+  --token <secret>     Secret URL path segment, at least 16 characters (default: random)
+  --allow-private-network   Over HTTP, let audits open localhost and private addresses
+  --reports <dir>      Where finished audits write reports (default: ~/ai-tag-debugger-reports)
+  --public-url <url>   The HTTPS address of your tunnel or host, so audits can link to reports`;
+
+const HELP = { run: RUN, plan: PLAN, replay: REPLAY, mcp: MCP };
+
+/** Help text for a command, or the top-level help when the command is unknown or missing. */
+export function helpText(command) {
+  return HELP[command] ?? MAIN;
+}

package/src/i18n.js

@@ -85,6 +85,12 @@ const en = {
     tabScope: "Scope and plan",
     sections: "Report sections",
     headerMeta: (journeys, providers) => `${journeys} ${journeys === 1 ? "journey" : "journeys"} · ${providers} ${providers === 1 ? "provider" : "providers"}`,
+    checkedAgainst: (id) => `Checked against plan ${id}`,
+    planVsSite: "Plan vs. site",
+    planVsSiteLead: "Each planned event, and what the site actually sent",
+    coverageLine: (c) => `Coverage ${c.implemented} of ${c.checkable}${c.percent === null ? "" : ` (${c.percent}%)`}${c.not_checked ? `, ${c.not_checked} ${c.not_checked === 1 ? "event" : "events"} not checked` : ""}`,
+    bucket: { implemented: "Implemented", missing: "Missing", missing_params: "Missing params", wrong_values: "Wrong values", unplanned: "Unplanned", not_checked: "Not checked" },
+    bucketCol: "Result",
     summaryLead: "AI summary, most important first",
     noSummary: "Run without --no-ai for an AI summary of the findings.",
     seeAllFindings: "See all findings →",
@@ -232,6 +238,12 @@ const tr = {
     tabScope: "Kapsam ve plan",
     sections: "Rapor bölümleri",
     headerMeta: (journeys, providers) => `${journeys} yolculuk · ${providers} sağlayıcı`,
+    checkedAgainst: (id) => `${id} planına göre kontrol edildi`,
+    planVsSite: "Plan ve site",
+    planVsSiteLead: "Plandaki her olay ve sitenin gerçekte gönderdiği",
+    coverageLine: (c) => `Kapsam ${c.checkable} olaydan ${c.implemented}${c.percent === null ? "" : ` (%${c.percent})`}${c.not_checked ? `, ${c.not_checked} olay kontrol edilmedi` : ""}`,
+    bucket: { implemented: "Uygulanmış", missing: "Eksik", missing_params: "Eksik parametre", wrong_values: "Hatalı değer", unplanned: "Planda yok", not_checked: "Kontrol edilmedi" },
+    bucketCol: "Sonuç",
     summaryLead: "Yapay zekâ özeti, öncelik sırasıyla",
     noSummary: "Bulguların yapay zekâ özeti için --no-ai olmadan çalıştırın.",
     seeAllFindings: "Tüm bulguları gör →",

package/src/journeys.js

@@ -64,11 +64,13 @@ export function presetFor(name) {
  * Adds a journey's preset events to a plan (a copy): events the plan already
  * has are expected on this journey too; missing ones are added for this journey.
  */
-export function withPresetEvents(plan, journeyId, preset) {
+export function withPresetEvents(plan, journeyId, preset, { addMissing = true } = {}) {
   const events = plan.events.map((e) => ({ ...e }));
   for (const pe of preset.events) {
-    const existing = events.find((e) => e.platform === pe.platform && e.name === pe.name);
-    if (!existing) events.push({ ...pe, journeys: [journeyId] });
+    const existing = events.find((e) => String(e.platform).toLowerCase() === pe.platform && e.name === pe.name);
+    if (!existing) {
+      if (addMissing) events.push({ ...pe, journeys: [journeyId] });
+    }
     else if (existing.journeys && !existing.journeys.includes(journeyId)) existing.journeys = [...existing.journeys, journeyId];
   }
   return { ...plan, events };
@@ -80,10 +82,20 @@ export function withPresetEvents(plan, journeyId, preset) {
  *   picks: journey ids from the config or preset names. goals: journeys described in plain language.
  *   events: only check these event names.
  */
-export function planRun({ config = {}, plan, picks = [], goals = [], events = [] }) {
-  // Copied, because the loops below add journeys to events.
-  let runPlan = { ...(plan ?? { events: [] }), events: (plan?.events ?? []).map((e) => ({ ...e })) };
+export function planRun({ config = {}, plan, picks = [], goals = [], events = [], against = false }) {
   const configJourneys = config.journeys ?? [];
+  // --against alone: the plan says what to walk.
+  if (against && !picks.length && !goals.length && !configJourneys.length) {
+    const derived = journeysFromPlan(plan);
+    return { journeys: derived.journeys, plan: onlyEvents(derived.plan, events) };
+  }
+  // --against with --journey or --goal: only plan events expected on those flows are checked;
+  // the rest are expected nowhere, so they are not checked rather than reported missing.
+  const scoped = against && (picks.length || goals.length);
+  let runPlan = {
+    ...(plan ?? { events: [] }),
+    events: (plan?.events ?? []).map((e) => (scoped ? { ...e, journeys: (e.journeys ?? []).filter((j) => picks.includes(j)) } : { ...e })),
+  };
   const journeys = [];
 
   for (const pick of picks) {
@@ -99,13 +111,13 @@ export function planRun({ config = {}, plan, picks = [], goals = [], events = []
     }
     if (journeys.some((j) => j.id === preset.id)) continue;
     journeys.push({ id: preset.id, goal: preset.goal });
-    runPlan = withPresetEvents(runPlan, preset.id, preset);
+    runPlan = withPresetEvents(runPlan, preset.id, preset, { addMissing: !scoped });
   }
 
   goals.forEach((goal, i) => {
     const id = goals.length > 1 ? `custom-${i + 1}` : "custom";
     journeys.push({ id, goal });
-    runPlan = expectEvents(runPlan, id, events);
+    runPlan = expectEvents(runPlan, id, scoped ? [...events, ...eventsNamedIn(goal, runPlan)] : events);
   });
 
   if (!picks.length && !goals.length) journeys.push(...configJourneys);
@@ -140,3 +152,70 @@ export function filterFindings(findings, events = []) {
   const wanted = new Set(events.map((e) => e.toLowerCase()));
   return findings.filter((f) => (f.event ? wanted.has(f.event.toLowerCase()) : f.check !== "unplanned_events"));
 }
+
+const words = (text) => String(text ?? "").toLowerCase().replace(/[_-]+/g, " ");
+
+/** Plan events a plain-language goal mentions, by event name ("add to cart" finds add_to_cart) or "<trigger page> page". */
+export function eventsNamedIn(goal, plan) {
+  const text = words(goal);
+  return plan.events
+    .filter((e) => text.includes(words(e.name)) || (e.trigger?.page && text.includes(`${words(e.trigger.page)} page`)))
+    .map((e) => e.name);
+}
+
+/** Which ready-made journey covers a group of plan events, from the standard GA4 shop and lead events in it. */
+const PRESET_BY_EVENT = [
+  ["purchase", ["purchase", "add_payment_info", "add_shipping_info", "begin_checkout"]],
+  ["add_to_cart", ["add_to_cart", "view_cart"]],
+  ["sign_up", ["sign_up"]],
+  ["lead", ["generate_lead"]],
+  ["search", ["search", "view_search_results"]],
+];
+
+export const MAX_PLAN_JOURNEYS = 6;
+
+const slug = (text) => words(text).trim().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "") || "page";
+
+function goalFor(page, events) {
+  const actions = [...new Set(events.map((e) => e.trigger?.element).filter(Boolean))];
+  const where = page ? `go to a ${page} page` : "browse the site";
+  const doing = actions.length ? ` and use ${actions.map((a) => `"${a}"`).join(", ")}` : "";
+  return `Accept cookies, ${where}${doing}. Never enter real payment details.`;
+}
+
+/**
+ * Journeys for `run --against` used alone: the plan's events grouped by the page they are triggered on
+ * (trigger.page), at most six, each with one goal built from the plan's trigger text (standard shop events
+ * reuse the ready-made journeys) and the group's events expected on it. Returns the journeys and the plan
+ * with each event's "journeys" set.
+ */
+export function journeysFromPlan(plan, max = MAX_PLAN_JOURNEYS) {
+  const groups = new Map();
+  for (const e of plan?.events ?? []) {
+    const page = e.trigger?.page ? String(e.trigger.page).trim() : "";
+    if (!groups.has(page)) groups.set(page, []);
+    groups.get(page).push(e);
+  }
+  // The biggest groups get their own journey; the rest share the last one.
+  let list = [...groups].map(([page, evs]) => ({ page, events: evs })).sort((a, b) => b.events.length - a.events.length);
+  if (list.length > max) {
+    const rest = list.slice(max - 1);
+    list = [...list.slice(0, max - 1), { page: rest.map((g) => g.page).filter(Boolean).join(", "), events: rest.flatMap((g) => g.events), merged: rest }];
+  }
+  const journeys = [];
+  const ids = new Map();
+  for (const group of list) {
+    const names = new Set(group.events.map((e) => e.name));
+    const presetId = PRESET_BY_EVENT.find(([, evs]) => evs.some((n) => names.has(n)))?.[0];
+    const base = presetId && !journeys.some((j) => j.id === presetId) ? presetId : slug(group.page);
+    let id = base;
+    for (let n = 2; journeys.some((j) => j.id === id); n++) id = `${base}_${n}`;
+    const goal = presetId === id ? JOURNEY_PRESETS[presetId].goal : group.merged ? group.merged.map((g) => goalFor(g.page, g.events)).join(" Then ") : goalFor(group.page, group.events);
+    journeys.push({ id, goal, planEvents: group.events.map((e) => e.name) });
+    for (const e of group.events) ids.set(e, id);
+  }
+  return {
+    journeys,
+    plan: { ...plan, events: (plan?.events ?? []).map((e) => ({ ...e, journeys: [ids.get(e)] })) },
+  };
+}

package/src/mcp.js

@@ -20,6 +20,7 @@ import { collect, pageView, SYSTEM_PROMPT } from "./agent.js";
 import { checkRun, groupFindings, summarize } from "./checks.js";
 import { LANGUAGES, messages } from "./i18n.js";
 import { loadConfig, readJson, runAudit, writeReports } from "./audit.js";
+import { DEFAULT_DATA_DIR, resolvePlan } from "./workspace.js";
 import { DEFAULT_PROVIDERS, PROVIDERS as TRACKING_PROVIDERS } from "./parsers.js";
 import { expectEvents, filterFindings, JOURNEY_PRESETS, onlyEvents, presetFor, withPresetEvents } from "./journeys.js";
 
@@ -33,7 +34,7 @@ const INSTRUCTIONS = `ai-tag-debugger checks a website's analytics and ad tracki
 
 Before starting, ask the user which platforms to check and suggest the default (${DEFAULT_PROVIDERS.map((k) => TRACKING_PROVIDERS[k]).join(", ")}); pass their choice as providers.
 
-To audit a journey yourself: call start_audit with the site URL and a journey (a ready-made one: ${Object.keys(JOURNEY_PRESETS).join(", ")}, or the user's own description), then browser_action one step at a time until the journey is done (each result shows the page and the tracking hits that step sent), then finish_audit with the measurement plan to get the findings and a full HTML report. Explain the findings to the user in plain language.
+To audit a journey yourself: call start_audit with the site URL and a journey (a ready-made one: ${Object.keys(JOURNEY_PRESETS).join(", ")}, or the user's own description), then browser_action one step at a time until the journey is done (each result shows the page and the tracking hits that step sent), then finish_audit (with against to check the run against a saved plan) to get the findings and the report. Explain the findings to the user in plain language.
 
 While browsing:
 ${SYSTEM_PROMPT.split("How to work:\n")[1]}`;
@@ -100,10 +101,27 @@ async function readPlan(plan, allowFiles) {
   return readJson(trimmed);
 }
 
+/** finish_audit refuses a bad plan without closing the audit, so the captured run is not lost. */
+const STILL_OPEN = "The audit is still open: call finish_audit again with a corrected plan (or none).";
+
+const AGAINST_DOC = "A saved plan to check against: latest (or last), first, a plan ID such as 2026-10-16_0627, or on a local server a path to a plan file or folder. Plans are the ones saved by `aitd plan --site <url>`.";
+
+/** Finds the saved plan named by `against`. Over HTTP only latest, first and plan IDs are allowed, never paths. */
+async function loadAgainst(ref, site, opts) {
+  if (!opts.allowFiles && !/^(latest|last|first|\d{4}-\d{2}-\d{2}_\d{4}(\d{2})?)$/.test(ref.trim())) {
+    throw new Error("Over HTTP, against takes latest, first or a plan ID, not a path.");
+  }
+  const found = await resolvePlan(ref, { dataDir: opts.dataDir ?? DEFAULT_DATA_DIR, site });
+  const plan = await readJson(found.file);
+  if (!Array.isArray(plan?.events)) throw new Error(`${found.file} is not a plan: it needs an "events" list.`);
+  return { found, plan };
+}
+
 /**
- * @param {{ allowFiles: boolean, blockPrivate?: boolean, reportsDir: string, reportsUrl?: string }} opts
+ * @param {{ allowFiles: boolean, blockPrivate?: boolean, reportsDir: string, reportsUrl?: string, dataDir?: string }} opts
  *   allowFiles: local (stdio) servers may read config and plan files; HTTP servers may not.
  *   blockPrivate: the browser refuses loopback, private and link-local addresses (HTTP servers, by default).
+ *   dataDir: where saved plans live (default ./aitd), used by `against`.
  *   reportsUrl: where an HTTP server serves finished reports, if it knows its public URL.
  */
 export function buildServer(opts) {
@@ -214,7 +232,7 @@ export function buildServer(opts) {
     {
       title: "Finish and check the audit",
       description:
-        "Closes the browser, checks every captured hit against the measurement plan (missing events, missing parameters, duplicates, hits before consent, Consent Mode defaults, emails sent in plain text, unplanned events) and writes a full HTML report with the event timeline. Returns the findings.",
+        "Closes the browser, checks every captured hit against the plan (missing events, missing parameters, duplicates, hits before consent, Consent Mode defaults, emails sent in plain text, unplanned events) and writes the report with the event timeline. Returns the findings. The plan is what should be tracked: pass a saved one with against, or write one inline with measurement_plan.",
       inputSchema: {
         audit_id: z.string(),
         completed: z.boolean().describe("Whether the journey reached its goal."),
@@ -223,21 +241,28 @@ export function buildServer(opts) {
           .string()
           .optional()
           .describe(
-            'The measurement plan as JSON text, e.g. {"consent_mode": true, "events": [{"platform": "ga4", "name": "purchase", "required_params": ["transaction_id", "value", "currency"]}]}. On a local server this can also be a file path. Without a plan, a ready-made journey checks its own events; otherwise only consent, duplicate and personal data checks run.',
+            'The plan (what should be tracked) as JSON text, e.g. {"consent_mode": true, "events": [{"platform": "ga4", "name": "purchase", "required_params": ["transaction_id", "value", "currency"]}]}. On a local server this can also be a file path. Without a plan, a ready-made journey checks its own events; otherwise only consent, duplicate and personal data checks run.',
           ),
+        against: z.string().optional().describe(`${AGAINST_DOC} The site comes from this audit. Use either against or measurement_plan, not both.`),
         events: z.array(z.string()).optional().describe("Only check these events, e.g. [\"purchase\", \"add_to_cart\"]. On your own journey, these events are also expected to fire."),
         language: z.enum(Object.keys(LANGUAGES)).optional().describe("Report language. Default en."),
         branding: z.boolean().optional().describe("Set false to leave the Analitik İşler logo and credit line out of the report."),
       },
     },
-    async ({ audit_id, completed, note, measurement_plan, events = [], language, branding }) => {
+    async ({ audit_id, completed, note, measurement_plan, against, events = [], language, branding }) => {
       const audit = getAudit(audit_id);
+      if (against && measurement_plan) return fail(`Use either against or measurement_plan, not both. ${STILL_OPEN}`);
       let plan;
+      let againstPlan = null;
       try {
-        plan = await readPlan(measurement_plan, opts.allowFiles);
+        if (against) {
+          const loaded = await loadAgainst(against, audit.site, opts);
+          plan = loaded.plan;
+          againstPlan = { ...loaded.found, label: loaded.found.id ?? path.relative(process.cwd(), loaded.found.file) };
+        } else plan = await readPlan(measurement_plan, opts.allowFiles);
         if (!Array.isArray(plan.events)) throw new Error('The plan needs an "events" list.');
       } catch (err) {
-        return fail(`Could not read the measurement plan: ${err.message}`);
+        return fail(`Could not read the plan: ${err.message} ${STILL_OPEN}`);
       }
       if (audit.preset) plan = withPresetEvents(plan, audit.journey, audit.preset);
       else plan = expectEvents(plan, audit.journey, events);
@@ -251,10 +276,11 @@ export function buildServer(opts) {
       const grouped = groupFindings(findings);
       const counts = summarize(grouped);
       const outDir = path.join(opts.reportsDir, `${new Date().toISOString().replace(/[:.]/g, "-")}-${audit.journey}`);
-      const reportPath = await writeReports({ outDir, config: { site: audit.site }, plan, runs: [run], findings, explained: null, lang, branding: branding !== false });
+      const reportPath = await writeReports({ outDir, config: { site: audit.site }, plan, runs: [run], findings, explained: null, lang, against: againstPlan, branding: branding !== false });
       const m = messages(lang);
       const lines = [
         m.ui.counts(counts),
+        ...(againstPlan ? [m.ui.checkedAgainst(againstPlan.label)] : []),
         "",
         ...grouped.filter((f) => f.severity !== "ok").map((f) => `- ${m.severity[f.severity]}: ${f.detail}${f.evidence ? ` (captured: ${f.evidence})` : ""} [${f.where.map((w) => m.ui.whereStep(w.journey, w.viewport, w.step)).join("; ")}]`),
         "",
@@ -278,9 +304,10 @@ export function buildServer(opts) {
       {
         title: "Run a configured audit",
         description:
-          "Runs every journey in a ai-tag-debugger config file. With scripted true, it replays each journey's fixed steps and needs no API key. Otherwise the journeys are browsed by the AI provider configured on this computer (ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY). Writes the reports and returns the findings.",
+          "Runs every journey in a ai-tag-debugger config file and writes the report. With against, the run is checked against a saved plan and, if the config has no journeys, walks the journeys derived from that plan. With scripted true, it replays each journey's fixed steps and needs no API key. Otherwise the journeys are browsed by the AI provider configured on this computer (ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY). Returns the findings.",
         inputSchema: {
           config: z.string().describe("Path to the config file, e.g. ai-tag-debugger.config.json"),
+          against: z.string().optional().describe(`${AGAINST_DOC} The site comes from the config.`),
           scripted: z.boolean().optional().describe("Replay fixed steps instead of browsing with an AI model. Default true."),
           language: z.enum(Object.keys(LANGUAGES)).optional(),
           branding: z.boolean().optional().describe("Set false to leave the Analitik İşler logo and credit line out of the report."),
@@ -290,12 +317,26 @@ export function buildServer(opts) {
             .describe(`Tracking providers to check. Default ${DEFAULT_PROVIDERS.join(", ")}. Requests to the others are still answered locally, but they are only counted, not shown or checked.`),
         },
       },
-      async ({ config: configFile, scripted, language, branding, providers }) => {
+      async ({ config: configFile, against, scripted, language, branding, providers }) => {
         const loaded = await loadConfig(configFile);
+        let againstPlan = null;
+        if (against) {
+          try {
+            const found = await loadAgainst(against, loaded.config.site, opts);
+            if (!loaded.config.site) {
+              if (!found.plan.site) throw new Error(`${found.found.file} has no "site" and the config has none either.`);
+              loaded.config = { ...loaded.config, site: found.plan.site };
+            }
+            loaded.plan = found.plan;
+            againstPlan = found.found;
+          } catch (err) {
+            return fail(`Could not read the plan: ${err.message}`);
+          }
+        }
         const replay = scripted !== false;
         let result;
         try {
-          result = await runAudit({ ...loaded, scripted: replay, ai: !replay, lang: language, branding, providers, outDir: path.join(opts.reportsDir, new Date().toISOString().replace(/[:.]/g, "-")) });
+          result = await runAudit({ ...loaded, scripted: replay, ai: !replay, lang: language, branding, providers, against: againstPlan, outDir: path.join(opts.reportsDir, new Date().toISOString().replace(/[:.]/g, "-")) });
         } catch (err) {
           // The CLI wording (--scripted --no-ai) means nothing to a chat app, so say it in this tool's terms.
           if (err.code !== "NO_API_KEY") throw err;

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/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>