@analitikisler/ai-tag-debugger 0.9.0 → 0.11.0

package/src/cli.js

@@ -3,79 +3,18 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { loadConfig, runAudit } from "./audit.js";
-import { LANGUAGES, messages } from "./i18n.js";
-import { PROVIDERS } from "./providers.js";
-import { JOURNEY_PRESETS } from "./journeys.js";
-import { PROVIDERS as TRACKING_PROVIDERS, DEFAULT_PROVIDERS } from "./parsers.js";
+import { messages } from "./i18n.js";
+import { helpText } from "./help.js";
 import { replaySavedSite, writeSavedSteps } from "./replay.js";
+import { savePlan } from "./plan.js";
+import { DEFAULT_DATA_DIR } from "./workspace.js";
+import { commandText, intentToArgs, isSentence, needsWhatToTest, translate } from "./ask.js";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
-const USAGE = `ai-tag-debugger: an open-source AI agent that QA-tests your analytics and ad tracking.
-
-Usage:
-  ai-tag-debugger run --site <url> --journey purchase [options]   Audit ready-made journeys, no config needed.
-  ai-tag-debugger run --site <url> --goal "<what to do>"          Audit a journey you describe in plain language.
-  ai-tag-debugger run --config <file> [options]                   Run an audit from a config file.
-  ai-tag-debugger replay <dir>... [--update]      Audit sites saved with --save-site again, offline and without AI,
-                                                  and list findings that changed. Exits with code 1 when any did.
-  ai-tag-debugger mcp [--http] [--port <n>]       Start the MCP server for Claude, ChatGPT, Gemini and other chat apps.
-
-Run options:
-  --site <url>         The site to audit (overrides "site" in the config).
-  --config <file>      Audit config (JSON). See examples/demo.config.json.
-  --journey <id>       Run this journey (repeatable): a journey id from the config, or a ready-made
-                       journey: ${Object.keys(JOURNEY_PRESETS).join(", ")}.
-  --goal "<text>"      Run a journey you describe in plain language (repeatable).
-  --events <names>     Only check these events, comma separated, e.g. purchase,add_to_cart.
-  --max-steps <n>      Most AI steps per journey (default 30). Lower it to cap API usage.
-  --out <dir>          Where to write report.html, report.md, timeline.csv and capture.json (default: reports/<timestamp>).
-  --provider <name>    AI provider: ${Object.keys(PROVIDERS).join(", ")} (default: whichever API key is set).
-  --model <id>         Model id (defaults: ${Object.entries(PROVIDERS).filter(([, p]) => p.defaultModel).map(([k, p]) => `${k} ${p.defaultModel}`).join(", ")}).
-  --base-url <url>     API address for --provider openai-compatible (Kimi, GLM, DeepSeek, OpenRouter, Ollama...).
-  --lang <code>        Report language: ${Object.keys(LANGUAGES).join(" or ")} (default: en, or "language" in the config).
-  --providers <list>   Tracking providers to check, comma separated (default: ${DEFAULT_PROVIDERS.join(",")}).
-                       Choose from ${Object.keys(TRACKING_PROVIDERS).join(", ")}. Requests to the
-                       others are still answered locally, but only counted ("providers" in the config).
-  --viewport <name>    Only run this viewport: desktop or mobile (repeatable).
-  --allow-host <host>  Let journeys visit this host too, e.g. a hosted checkout (repeatable). By default the
-                       browser stays on the audited site and its subdomains ("allowed_hosts" in the config).
-  --scripted           Replay each journey's fixed "steps" instead of letting the AI browse.
-  --no-ai              Use no AI model at all (requires --scripted). The report then has no explanations.
-  --fail-on <level>    Exit with code 1 when findings reach this level: broken, risk, warning or never (default: broken).
-  --headed             Show the browser window.
-  --keep-bodies        Store tracking requests as sent. By default, emails, phone numbers and user ids sent
-                       for ad matching are redacted in the report and capture.json ("keep_bodies" in the config).
-  --no-branding        Leave the Analitik İşler logo and credit line out of the reports ("branding": false in the config).
-  --save-site <dir>    Also save the site's responses and the steps taken in this folder, so "replay" can audit
-                       the same pages again offline. Its findings become the expected ones.
-  --save-steps <file>  Write the steps each journey took into "journeys[].steps" of this config file (created
-                       if missing), so "run --config <file> --scripted --no-ai" repeats them with no AI model
-                       or API key. A journey run on several viewports keeps the steps of the first.
-
-Replay options:
-  --update             Make this replay's findings the expected ones (after checking that the changes are right).
-  --out <dir>          Where to write the replay's reports (default: <dir>/last-replay).
-
-MCP options:
-  --http               Serve over Streamable HTTP instead of stdio (for apps that connect to a URL).
-  --port <n>           HTTP port (default 8787).
-  --host <addr>        HTTP host (default 127.0.0.1).
-  --token <secret>     Secret URL path segment, at least 16 characters (default: random, printed at start).
-  --allow-private-network  Over HTTP, let audits open localhost and private network addresses (blocked by default).
-  --reports <dir>      Where finished audits write reports (default: ~/ai-tag-debugger-reports).
-  --public-url <url>   The HTTPS address your tunnel or host gives this server, so audits can link to their reports.
-
-  -h, --help           Show this help.
-  -v, --version        Print the version.
-
-Short alias: aitd (aitd run ... is the same as ai-tag-debugger run ...).
-
-API keys: set one of ${Object.values(PROVIDERS).map((p) => p.env).join(", ")}.
-Any OpenAI-compatible API: --provider openai-compatible --base-url <url> --model <id>, with the key in OPENAI_COMPATIBLE_API_KEY.`;
-
-async function main() {
+async function main(args = process.argv.slice(2)) {
   const { values, positionals } = parseArgs({
+    args,
     allowPositionals: true,
     options: {
       config: { type: "string" },
@@ -86,6 +25,7 @@ async function main() {
       out: { type: "string" },
       journey: { type: "string", multiple: true },
       viewport: { type: "string", multiple: true },
+      platforms: { type: "string", multiple: true },
       providers: { type: "string", multiple: true },
       "allow-host": { type: "string", multiple: true },
       "allow-private-network": { type: "boolean", default: false },
@@ -108,6 +48,13 @@ async function main() {
       "save-site": { type: "string" },
       "save-steps": { type: "string" },
       update: { type: "boolean", default: false },
+      "data-dir": { type: "string" },
+      against: { type: "string" },
+      from: { type: "string" },
+      topic: { type: "string" },
+      format: { type: "string" },
+      force: { type: "boolean", default: false },
+      yes: { type: "boolean", short: "y", default: false },
       help: { type: "boolean", short: "h", default: false },
       version: { type: "boolean", short: "v", default: false },
     },
@@ -118,6 +65,11 @@ async function main() {
     return;
   }
 
+  if (isSentence(positionals) && !values.help) {
+    const next = await fromSentence(positionals[0], values, args);
+    if (next) await main(next);
+    return;
+  }
   if (command === "mcp" && !values.help) {
     const { startMcp } = await import("./mcp.js");
     await startMcp({ http: values.http, port: values.port ? Number(values.port) : undefined, host: values.host, token: values.token, reportsDir: values.reports, publicUrl: values["public-url"], allowPrivateNetwork: values["allow-private-network"] });
@@ -145,19 +97,76 @@ async function main() {
     if (changed && !values.update) process.exitCode = 1;
     return;
   }
-  if (values.help || command !== "run" || (!values.config && !values.site)) {
-    console.log(USAGE);
-    process.exit(values.help ? 0 : 2);
+  if (command === "plan" && positionals[1] === "list" && !values.help) {
+    if (!values.site) throw new Error("plan list needs --site <url>: aitd plan list --site https://www.example.com");
+    const { domainOf, listPlanIds } = await import("./workspace.js");
+    const ids = await listPlanIds(values["data-dir"] ?? DEFAULT_DATA_DIR, values.site);
+    if (!ids.length) throw new Error(`No plan yet for ${domainOf(values.site)}. Draft one with: aitd plan --site ${values.site}`);
+    for (const id of ids) console.log(id);
+    return;
   }
-  if (values["no-ai"] && !values.scripted) {
-    throw new Error("--no-ai needs --scripted: without an AI model, journeys must have fixed steps.");
+  if (command === "plan" && !values.help && ["import", "export"].includes(positionals[1])) {
+    await planSheet(positionals[1], positionals[2], values);
+    return;
+  }
+  if (command === "plan" && !values.help) {
+    if (values.from) throw new Error("--from was removed. Draft a plan with: aitd plan --site <url>");
+    if (values.out) throw new Error("plan --out was removed. Plans are saved in aitd/<domain>/plans/<id>/; use --data-dir <dir> to keep them elsewhere.");
+    if (values.force) throw new Error("--force was removed. Each plan is saved in a new folder, so nothing is replaced.");
+    if (!values.site) throw new Error("plan needs --site <url>: aitd plan --site https://www.example.com");
+    if (values.topic !== undefined) (await import("./discover.js")).checkTopic(values.topic);
+    const dataDir = values["data-dir"] ?? DEFAULT_DATA_DIR;
+    const { domainOf } = await import("./workspace.js");
+    domainOf(values.site); // Checked before the browser starts.
+    const maxSteps = values["max-steps"] ? Number(values["max-steps"]) : undefined;
+    if (maxSteps !== undefined && !(Number.isInteger(maxSteps) && maxSteps > 0)) throw new Error("--max-steps must be a positive whole number.");
+    const { createProvider } = await import("./providers.js");
+    const { discoverPlan } = await import("./discover.js");
+    const provider = await createProvider({ name: values.provider, model: values.model, baseUrl: values["base-url"] });
+    console.log(`Exploring ${values.site} to draft its measurement plan…`);
+    const { plan } = await discoverPlan({ site: values.site, topic: values.topic, provider, maxSteps, headed: values.headed, allowedHosts: values["allow-host"], log: console.log });
+    const { id, dir } = await savePlan(plan, { dataDir, site: values.site, branding: !values["no-branding"] });
+    const custom = plan.events.filter((e) => e.custom).length;
+    const rel = path.relative(process.cwd(), dir);
+    console.log(`✓ Saved plan ${id}: ${plan.events.length} events (${custom} custom) and ${plan.user_properties.length} user properties in ${rel.startsWith("..") ? dir : rel}`);
+    return;
   }
+  if (values.help || command !== "run" || (!values.config && !values.site && !values.against)) {
+    console.log(helpText(command));
+    process.exit(values.help ? 0 : 2);
+  }
+  if (values["no-ai"]) values.scripted = true; // Without an AI model the journeys can only replay fixed steps.
+  if (values.providers?.length) console.log("--providers is now --platforms.");
+  const platforms = [...(values.platforms ?? []), ...(values.providers ?? [])];
   const levels = ["broken", "risk", "warning"];
   const failOn = values["fail-on"];
   if (failOn !== "never" && !levels.includes(failOn)) throw new Error(`--fail-on must be one of ${levels.join(", ")}, never.`);
 
   const loaded = values.config ? await loadConfig(values.config) : { config: {}, plan: null, gtmContainer: null };
   if (values.site) loaded.config = { ...loaded.config, site: values.site };
+  if (!values.against && !values.journey?.length && !values.goal?.length && !loaded.config.journeys?.length) {
+    throw new Error('Nothing to test. Add --against latest, --journey <id> or --goal "<text>".');
+  }
+  let against = null;
+  if (values.against) {
+    const { readJson } = await import("./audit.js");
+    const { resolvePlan } = await import("./workspace.js");
+    if (loaded.config.site) {
+      try {
+        new URL(loaded.config.site);
+      } catch {
+        throw new Error(`"${loaded.config.site}" is not a full URL. Use e.g. https://www.example.com`);
+      }
+    }
+    against = await resolvePlan(values.against, { dataDir: values["data-dir"] ?? DEFAULT_DATA_DIR, site: loaded.config.site });
+    const plan = await readJson(against.file);
+    if (!Array.isArray(plan?.events)) throw new Error(`${against.file} is not a plan: it needs an "events" list.`);
+    if (!loaded.config.site) {
+      if (!plan.site) throw new Error(`${against.file} has no "site". Add --site <url>.`);
+      loaded.config = { ...loaded.config, site: plan.site };
+    }
+    loaded.plan = plan;
+  }
   if (values["keep-bodies"]) loaded.config = { ...loaded.config, keep_bodies: true };
   if (values["allow-host"]?.length) loaded.config = { ...loaded.config, allowed_hosts: [...(loaded.config.allowed_hosts ?? []), ...values["allow-host"]] };
   try {
@@ -167,6 +176,8 @@ async function main() {
   }
   const maxSteps = values["max-steps"] ? Number(values["max-steps"]) : undefined;
   if (maxSteps !== undefined && !(Number.isInteger(maxSteps) && maxSteps > 0)) throw new Error("--max-steps must be a positive whole number.");
+  // run --out is a hidden alias kept for one minor version; --data-dir replaces it.
+  if (values.out) console.log("Note: run --out will be removed in a later version. Runs are saved in aitd/<domain>/runs/<id>/; use --data-dir <dir> to keep them elsewhere.");
   const result = await runAudit({
     ...loaded,
     journeys: values.journey,
@@ -174,7 +185,7 @@ async function main() {
     events: (values.events ?? []).flatMap((e) => e.split(",")).map((e) => e.trim()).filter(Boolean),
     maxSteps,
     viewports: values.viewport,
-    providers: values.providers?.length ? values.providers.flatMap((p) => p.split(",")) : undefined,
+    providers: platforms.length ? platforms.flatMap((p) => p.split(",")) : undefined,
     scripted: values.scripted,
     ai: !values["no-ai"],
     provider: values.provider,
@@ -184,7 +195,9 @@ async function main() {
     headed: values.headed,
     branding: values["no-branding"] ? false : undefined,
     outDir: values.out,
+    dataDir: values["data-dir"],
     saveSite: values["save-site"],
+    against,
     log: (msg) => console.log(msg),
   });
 
@@ -209,6 +222,95 @@ async function main() {
   }
 }
 
+// aitd "check my GA tags": shows the matching command and runs it once confirmed.
+async function fromSentence(sentence, values, extra) {
+  const { createProvider } = await import("./providers.js");
+  const provider = await createProvider({ name: values.provider, model: values.model, baseUrl: values["base-url"] }).catch((err) => {
+    if (err.code === "NO_API_KEY") return null;
+    throw err;
+  });
+  let { intent } = await translate(sentence, { provider });
+  let r = intentToArgs(intent);
+  if (r.question) {
+    const answer = (await ask(`${r.question} `)).toLowerCase();
+    if (!["plan", "run"].includes(answer)) throw new Error('Answer "plan" or "run", or type the command, e.g. aitd run --help.');
+    r = intentToArgs({ ...intent, action: answer });
+    intent = { ...intent, action: answer };
+  }
+  if (r.unsupported) throw new Error(r.unsupported);
+  let args = r.args;
+  const needsSite = !values.site && !args.includes("--site") && (args[0] === "plan" || !args.includes("--against"));
+  if (needsSite) {
+    const site = await ask("Which site? (e.g. https://www.example.com) ");
+    if (!site) throw new Error("A site is needed. Add it to the sentence or pass --site <url>.");
+    r = intentToArgs({ ...intent, site });
+    args = r.args;
+  }
+  if (needsWhatToTest(args)) args = await whatToTest(args, values);
+  // Options typed next to the sentence (--site, --provider, --headed…) carry over.
+  args = [...args, ...extra.filter((a) => a !== sentence && a !== "-y" && a !== "--yes")];
+  console.log(commandText(args));
+  if (!values.yes) {
+    const answer = (await ask("Run this? (Y/n) ")).toLowerCase();
+    if (answer && !["y", "yes"].includes(answer)) return null;
+  }
+  return args;
+}
+
+// A run needs something to test: suggest the site's latest plan, else ask for a goal.
+async function whatToTest(args, values) {
+  const site = values.site ?? args[args.indexOf("--site") + 1];
+  const { listPlanIds } = await import("./workspace.js");
+  const hasPlan = (await listPlanIds(values["data-dir"] ?? DEFAULT_DATA_DIR, site).catch(() => [])).length > 0;
+  if (hasPlan) {
+    const answer = values.yes ? "" : (await ask("Check against the latest plan? (Y/n) ")).toLowerCase();
+    if (!answer || ["y", "yes"].includes(answer)) return [...args, "--against", "latest"];
+  } else if (values.yes) {
+    throw new Error('Nothing to test yet. Say what to check, e.g. aitd "check my GA tags on the contact form", or draft a plan first.');
+  }
+  const goal = await ask("What should I check, e.g. the contact form? ");
+  if (!goal) throw new Error('Nothing to test. Say what to check, e.g. aitd "check my GA tags on the contact form".');
+  return [...args, "--goal", goal];
+}
+
+async function ask(question) {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function planSheet(action, arg, values) {
+  const dataDir = values["data-dir"] ?? DEFAULT_DATA_DIR;
+  const shown = (p) => {
+    const rel = path.relative(process.cwd(), p);
+    return rel.startsWith("..") ? p : rel;
+  };
+  const { readPlanSheet, writePlanSheet } = await import("./sheet.js");
+  if (action === "import") {
+    if (!arg) throw new Error("plan import needs a file: aitd plan import plan.xlsx --site https://www.example.com");
+    if (!values.site) throw new Error(`plan import needs --site <url>: aitd plan import ${arg} --site https://www.example.com`);
+    const { domainOf } = await import("./workspace.js");
+    domainOf(values.site);
+    const { plan, warnings } = await readPlanSheet(arg, { site: values.site });
+    for (const w of warnings) console.log(`Warning: ${w}`);
+    const { id, dir } = await savePlan(plan, { dataDir, site: values.site });
+    console.log(`✓ Imported plan ${id}: ${plan.events.length} events and ${plan.user_properties.length} user properties in ${shown(dir)}`);
+    return;
+  }
+  if (!arg) throw new Error("plan export needs a plan: aitd plan export latest --site https://www.example.com");
+  const format = (values.format ?? "xlsx").toLowerCase();
+  if (!["xlsx", "csv"].includes(format)) throw new Error(`--format must be xlsx or csv (found "${values.format}").`);
+  const { resolvePlan } = await import("./workspace.js");
+  const { file } = await resolvePlan(arg, { dataDir, site: values.site });
+  const plan = JSON.parse(readFileSync(file, "utf8"));
+  const written = await writePlanSheet(plan, path.dirname(file), { format });
+  console.log(`✓ Exported the plan to ${written.map(shown).join(" and ")}. Edit it, then save it as a new plan with: aitd plan import ${shown(written[0])} --site ${values.site ?? plan.site ?? "<url>"}`);
+}
+
 main().catch((err) => {
   console.error(`Error: ${err.message}`);
   process.exit(2);

package/src/discover.js

@@ -0,0 +1,185 @@
+import { AuditSession } from "./browser.js";
+import { runAgentJourney, StepTimeout } from "./agent.js";
+
+/** The goal of the browsing part: one page of each type, nothing submitted. */
+export const DISCOVER_GOAL = `Explore this site to draft its analytics measurement plan. You are not completing a purchase or any other task: visit ONE example of each kind of page that exists here and look at what a visitor can do on it, then call finish with success true.
+Visit, where the site has them (a small site may have only a few; that is fine, don't look for pages that aren't linked): the home page, one category or listing page, one product, item or article page, the cart (add one item first if there is an add-to-cart button), the first checkout step, the search results (search for something the site sells), and the sign-up, login, contact or newsletter forms.
+Rules: never pay, never submit a form with personal details, never open more than one page of the same kind, and accept the cookie banner when it appears. Stop as soon as every kind of page above has been seen once.`;
+
+const PLAN_SYSTEM = `You are a senior digital analytics consultant writing a GA4 measurement plan for a website that may have no tracking yet. You get the pages an explorer visited (their type, address, visible text and interactive elements) and any tracking hits the site already sent.
+
+Propose the events this site should track:
+- Recommended GA4 events where they fit (page_view, view_item_list, view_item, select_item, add_to_cart, view_cart, begin_checkout, purchase, search, sign_up, login, generate_lead, ...), with GA4's recommended parameters.
+- Custom events for interactions specific to this site that a business would want to measure (for example a size guide, a store locator, a video, a configurator, a filter, a download). Name them in snake_case and mark them custom.
+- For each event: what the visitor does, the page type and element that triggers it (quote the element's visible label), its parameters (standard and custom) with one realistic example value taken from the pages when possible, and which parameters are required.
+- Suggested user properties (for example customer_type, logged_in, membership_level), with a description and example.
+Only propose what the pages show is possible. Prefer fewer, useful events over many trivial ones.`;
+
+/** Kinds of events a plan can be limited to with --topic: what to explore, what to propose, and which events to keep. */
+const ECOMMERCE = new Set(["view_item_list", "select_item", "view_item", "add_to_cart", "remove_from_cart", "view_cart", "add_to_wishlist", "begin_checkout", "add_shipping_info", "add_payment_info", "purchase", "refund", "view_promotion", "select_promotion"]);
+const FORMS = new Set(["sign_up", "login", "generate_lead"]);
+export const TOPICS = {
+  "custom-events": {
+    explore: "the pages with interactions specific to this site (tools, filters, videos, downloads, configurators, locators)",
+    propose: "custom events for interactions specific to this site. Do not propose GA4 recommended events",
+    keep: (ev) => Boolean(ev.custom),
+  },
+  ecommerce: {
+    explore: "the home page, one listing page, one product page, the cart (add one item first) and the first checkout step",
+    propose: "the GA4 ecommerce events (view_item_list, select_item, view_item, add_to_cart, remove_from_cart, view_cart, begin_checkout, add_shipping_info, add_payment_info, purchase, and promotions) with their items parameters",
+    keep: (ev) => ECOMMERCE.has(ev.name),
+  },
+  forms: {
+    explore: "the sign-up, login, contact and newsletter forms",
+    propose: "form events: sign_up, login, generate_lead, and custom form events (for example form_start, form_submit, form_error, newsletter_signup). Never propose ecommerce events",
+    keep: (ev) => FORMS.has(ev.name) || /form|newsletter|subscribe|signup|sign_up|lead|contact/.test(ev.name),
+  },
+  consent: {
+    explore: "the cookie or consent banner and any privacy settings page. Open the banner's settings before accepting it",
+    propose: "consent events: the banner shown, accepted, rejected and customised (for example consent_banner_view, consent_update), with the chosen categories as parameters. Never propose ecommerce or form events",
+    keep: (ev) => /consent|cookie|privacy|gdpr/.test(ev.name),
+  },
+};
+
+/** Checks a --topic value; undefined means no topic (the whole plan). */
+export function checkTopic(topic) {
+  if (topic === undefined) return undefined;
+  if (!Object.hasOwn(TOPICS, topic)) throw new Error(`Unknown --topic "${topic}". Use one of: ${Object.keys(TOPICS).join(", ")}`);
+  return topic;
+}
+
+const str = { type: "string" };
+const PLAN_SCHEMA = {
+  type: "object",
+  properties: {
+    pages: { type: "array", items: { type: "object", properties: { type: str, url: str }, required: ["type", "url"], additionalProperties: false } },
+    events: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: str,
+          custom: { type: "boolean" },
+          description: str,
+          trigger_page: str,
+          trigger_element: str,
+          parameters: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { name: str, custom: { type: "boolean" }, required: { type: "boolean" }, description: str, example: str },
+              required: ["name", "custom", "required", "description", "example"],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ["name", "custom", "description", "trigger_page", "trigger_element", "parameters"],
+        additionalProperties: false,
+      },
+    },
+    user_properties: {
+      type: "array",
+      items: { type: "object", properties: { name: str, description: str, example: str }, required: ["name", "description", "example"], additionalProperties: false },
+    },
+  },
+  required: ["pages", "events", "user_properties"],
+  additionalProperties: false,
+};
+
+/** Page types the plan reports on; a site that has fewer of them (a two-page site) is normal, not a failure. */
+export const PAGE_TYPES = ["home", "listing", "detail", "search", "cart", "checkout", "signup", "login", "contact", "newsletter"];
+
+/** Which of PAGE_TYPES the plan's pages cover, and which are absent. Unrecognised type names are ignored. */
+export function pageTypeCoverage(pages = []) {
+  const norm = (t) => String(t ?? "").toLowerCase().replace(/[\s_-]+/g, "");
+  const aliases = { homepage: "home", category: "listing", product: "detail", item: "detail", article: "detail", register: "signup", registration: "signup", basket: "cart", lead: "contact", form: "contact" };
+  const found = new Set(pages.map((p) => aliases[norm(p.type)] ?? norm(p.type)));
+  return { found: PAGE_TYPES.filter((t) => found.has(t)), absent: PAGE_TYPES.filter((t) => !found.has(t)) };
+}
+
+const MAX_PAGES = 15;
+const cut = (s, n) => (s && s.length > n ? `${s.slice(0, n)}…` : s ?? "");
+
+/** One entry per address the explorer saw, keeping the last (fullest) view of each. */
+export function pagesSeen(snapshots) {
+  const byUrl = new Map();
+  for (const s of snapshots) {
+    if (!s?.url || s.url === "about:blank") continue;
+    const key = s.url.split("#")[0];
+    byUrl.delete(key);
+    byUrl.set(key, { url: key, title: s.title, elements: cut(s.elements, 4000), text: cut(s.text, 1500) });
+  }
+  return [...byUrl.values()].slice(-MAX_PAGES);
+}
+
+/** Turns the model's answer into the plan file: the audit's fields plus descriptions, triggers, parameters and user properties. */
+export function toPlan(site, answer, hits = []) {
+  const seen = new Set(hits.filter((h) => h.platform === "ga4").map((h) => h.name));
+  return {
+    site,
+    consent_mode: true,
+    pages: answer.pages ?? [],
+    events: (answer.events ?? []).map((ev) => {
+      const params = ev.parameters ?? [];
+      const required = params.filter((p) => p.required).map((p) => p.name);
+      return {
+        platform: "ga4",
+        name: ev.name,
+        ...(ev.custom ? { custom: true } : {}),
+        description: ev.description,
+        trigger: { page: ev.trigger_page, element: ev.trigger_element },
+        ...(required.length ? { required_params: required } : {}),
+        parameters: Object.fromEntries(params.map((p) => [p.name, { ...(p.custom ? { custom: true } : {}), description: p.description, example: p.example }])),
+        ...(seen.has(ev.name) ? { seen: true } : {}),
+      };
+    }),
+    user_properties: answer.user_properties ?? [],
+  };
+}
+
+/**
+ * Lets the AI explore the site (one page per type), then asks it for a measurement plan.
+ * With `topic`, exploring and the plan are limited to that kind of event (see TOPICS).
+ * @param {{ site: string, topic?: string, provider: any, maxSteps?: number, headed?: boolean, allowedHosts?: string[], viewport?: string, blockPrivate?: boolean, log?: (msg: string) => void }} opts
+ */
+export async function discoverPlan(opts) {
+  const log = opts.log ?? (() => {});
+  const topic = TOPICS[checkTopic(opts.topic)];
+  const goal = topic ? `${DISCOVER_GOAL}\nThis plan covers only ${opts.topic}: visit just ${topic.explore}, and skip other kinds of page.` : DISCOVER_GOAL;
+  const session = new AuditSession({ viewport: opts.viewport ?? "desktop", site: opts.site, allowedHosts: opts.allowedHosts, headless: !opts.headed, blockPrivate: opts.blockPrivate });
+  const snapshots = [];
+  let outcome;
+  try {
+    await session.start();
+    const startError = await session.act({ action: "goto", url: opts.site, reason: `Open ${opts.site}` });
+    if (startError) throw new Error(`Could not open ${opts.site}: ${startError}`);
+    const snapshot = session.snapshot.bind(session);
+    session.snapshot = async () => {
+      const s = await snapshot();
+      snapshots.push(s);
+      return s;
+    };
+    outcome = await runAgentJourney(session, { id: "discover", goal }, { provider: opts.provider, maxSteps: opts.maxSteps ?? 25, log }).catch((err) => {
+      if (err instanceof StepTimeout) return { completed: false, note: err.message };
+      throw err;
+    });
+  } finally {
+    await session.close();
+  }
+  const pages = pagesSeen(snapshots);
+  if (!pages.length) throw new Error("The explorer saw no pages, so there is nothing to plan from.");
+  log(`\nExplored ${pages.length} pages${outcome.completed ? "" : ` (${outcome.note})`}. Drafting the plan…`);
+  const existing = [...new Set(session.hits.map((h) => `${h.platform}:${h.name}`))];
+  const result = await opts.provider.json({
+    system: topic ? `${PLAN_SYSTEM}\nThis plan covers only ${opts.topic}. Propose only ${topic.propose}.` : PLAN_SYSTEM,
+    texts: [`Site: ${opts.site}`, `Pages visited:\n${JSON.stringify(pages, null, 1)}`, `Tracking hits the site already sends: ${existing.length ? existing.join(", ") : "none"}`],
+    schema: PLAN_SCHEMA,
+  });
+  if (result.error) throw new Error(`The model did not return a plan (${result.error}).`);
+  const plan = toPlan(opts.site, result.value, session.hits);
+  if (topic) plan.events = plan.events.filter(topic.keep);
+  const coverage = pageTypeCoverage(plan.pages);
+  log(`Page types found: ${coverage.found.join(", ") || "none"}`);
+  if (coverage.absent.length) log(`Not present on this site: ${coverage.absent.join(", ")}`);
+  return { plan, outcome, coverage };
+}

package/src/help.js

@@ -0,0 +1,107 @@
+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
+  aitd "check my GA tags on example.com"    (shows the command first; -y skips the question)
+
+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. Each run is saved in
+aitd/<domain>/runs/<id>/ and its report says what changed since the site's previous run.
+
+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)
+  --topic <name>       Only plan one kind of event: custom-events, ecommerce, forms or consent
+  --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;
+}