@analitikisler/ai-tag-debugger 0.8.2 → 0.10.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
   "mcpName": "io.github.analitikisler/ai-tag-debugger",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "Open-source AI agent that QA-tests your website's analytics, ad and consent tracking (GA4, GTM, Google Ads, Meta, TikTok). Bring your own model (Claude, OpenAI, Gemini) or use it from your chat app over MCP.",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
     "setup": "node scripts/setup.js",
     "test": "node --test test/*.test.js",
     "demo:serve": "node examples/serve.js",
-    "demo": "node src/cli.js run --config examples/demo.config.json --scripted --no-ai --out reports/demo"
+    "demo": "node src/cli.js run --config examples/demo.config.json --scripted --no-ai"
   },
   "engines": {
     "node": ">=20"
@@ -57,5 +57,8 @@
     "openai": "^7.30.1",
     "playwright": "1.56.1",
     "zod": "^4.6.5"
+  },
+  "optionalDependencies": {
+    "fflate": "^0.8.3"
   }
 }

package/src/agent.js

@@ -95,7 +95,7 @@ const TIMEOUTS = { model: 180_000, action: 120_000, page: 60_000 };
 
 const LAST_STEP_WAIT_MS = 3000;
 
-class StepTimeout extends Error {}
+export class StepTimeout extends Error {}
 
 /** The promise's value, or a StepTimeout with this message once ms have passed. */
 function withTimeout(promise, ms, message) {

package/src/audit.js

@@ -1,14 +1,15 @@
 // A full audit from a config file: run every journey, check, explain, write the reports.
 // Shared by the CLI and the MCP server's run_audit tool.
+import { newRunDir } from "./workspace.js";
 import { readFile, mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { failedRun, runJourney } from "./agent.js";
 import { VIEWPORTS } from "./browser.js";
-import { checkRun, groupFindings, summarize } from "./checks.js";
+import { checkRun, groupFindings, planCheck, summarize } from "./checks.js";
 import { explainFindings, renderCsv, renderHtml, renderMarkdown } from "./report.js";
 import { LANGUAGES, messages } from "./i18n.js";
 import { createProvider } from "./providers.js";
-import { filterFindings, planRun } from "./journeys.js";
+import { filterFindings, JOURNEY_PRESETS, planRun } from "./journeys.js";
 import { resolveProviders } from "./parsers.js";
 import { SAVED_SITE_FILE, writeSavedSite } from "./replay.js";
 
@@ -32,30 +33,33 @@ export async function loadConfig(configFile) {
   return { config, plan, gtmContainer };
 }
 
-export const defaultOutDir = () => path.resolve("reports", new Date().toISOString().replace(/[:.]/g, "-"));
 
-/** Writes report.md, report.html, timeline.csv and capture.json. */
-export async function writeReports({ outDir, config, plan, runs, findings, explained, lang, branding = config.branding !== false }) {
+/** Writes report.md, report.html, timeline.csv and capture.json, plus plan-check.json with --against. */
+export async function writeReports({ outDir, config, plan, runs, findings, explained, lang, against = null, branding = config.branding !== false }) {
   await mkdir(outDir, { recursive: true });
   const title = messages(lang).ui.title(new URL(config.site).hostname);
   const generatedAt = new Date().toISOString().slice(0, 16).replace("T", " ") + " UTC";
-  const report = { title, generatedAt, findings, explained, runs, plan, lang, branding };
+  const check = against ? { plan_id: against.id ?? null, ...planCheck(plan, runs, findings) } : null;
+  const report = { title, generatedAt, findings, explained, runs, plan, lang, branding, against: against?.label ?? null, planCheck: check };
   await writeFile(path.join(outDir, "report.md"), renderMarkdown(report));
   await writeFile(path.join(outDir, "report.html"), renderHtml(report));
   await writeFile(path.join(outDir, "timeline.csv"), renderCsv(report));
-  await writeFile(path.join(outDir, "capture.json"), JSON.stringify({ config: { ...config, plan }, runs, findings, explained }, null, 2));
+  if (check) await writeFile(path.join(outDir, "plan-check.json"), JSON.stringify(check, null, 2));
+  await writeFile(path.join(outDir, "capture.json"), JSON.stringify({ config: { ...config, plan }, ...(against ? { against: { plan_id: against.id, file: against.file } } : {}), runs, findings, explained }, null, 2));
   return path.join(outDir, "report.html");
 }
 
 /**
  * @param {{ config: any, plan?: any, gtmContainer?: any, journeys?: string[], goals?: string[], events?: string[], viewports?: string[],
  *   scripted?: boolean, ai?: boolean, provider?: string, model?: string, baseUrl?: string, maxSteps?: number, lang?: string, headed?: boolean,
- *   outDir?: string, branding?: boolean, providers?: string[], saveSite?: string, replaySite?: string, log?: (m: string) => void }} opts
+ *   outDir?: string, dataDir?: string, branding?: boolean, providers?: string[], saveSite?: string, replaySite?: string, log?: (m: string) => void }} opts
  *   journeys: config journey ids or ready-made journeys (purchase, add_to_cart, sign_up, lead, search).
  *   goals: extra journeys described in plain language. events: only check these events.
  *   providers: tracking providers to check (default: config "providers", else GA4, Google Ads, Meta, TikTok).
  *   saveSite: record the site's responses and the steps taken into this folder, for replaySite (see replay.js).
  *   replaySite: answer every request from a folder saved with saveSite, without the network.
+ *   against: { id, file } of the plan given with --against; opts.plan is then that plan. Used alone, the
+ *   journeys come from the plan; with journeys or goals, only the plan events expected on them are checked.
  */
 export async function runAudit(opts) {
   const { gtmContainer } = opts;
@@ -68,19 +72,29 @@ export async function runAudit(opts) {
   const useAi = opts.ai !== false;
   if (!useAi && !opts.scripted) throw new Error("Without an AI model, journeys must be replayed from their fixed steps (scripted).");
 
-  const { journeys, plan } = planRun({ config, plan: opts.plan, picks: opts.journeys, goals: opts.goals, events });
+  const against = opts.against ? { ...opts.against, label: opts.against.id ?? path.relative(process.cwd(), opts.against.file) } : null;
+  const { journeys, plan } = planRun({ config, plan: opts.plan, picks: opts.journeys, goals: opts.goals, events, against: Boolean(against) });
   config = { ...config, providers: resolveProviders(opts.providers ?? config.providers, plan) };
   const viewports = opts.viewports?.length ? opts.viewports : config.viewports ?? ["desktop"];
   const allowed = Object.keys(VIEWPORTS).join(", ");
   if (!Array.isArray(viewports)) throw new Error(`"viewports" must be a list, e.g. ["desktop", "mobile"]. Allowed values: ${allowed}.`);
   const unknown = viewports.filter((v) => !Object.hasOwn(VIEWPORTS, v));
   if (unknown.length) throw new Error(`Unknown viewport ${unknown.map((v) => `"${v}"`).join(", ")}. Use: ${allowed}.`);
-  if (!journeys.length) throw new Error("No journeys to run. Pick one with --journey (e.g. purchase) or describe one with --goal.");
+  if (!journeys.length) throw new Error(`No journeys to run. A run needs one of:\n  --journey <name>   one of: ${Object.keys(JOURNEY_PRESETS).join(", ")} (or a journey id from your config)\n  --goal "<text>"    describe what to do in your own words\n  --config <file>    a config file with "journeys"\nNot sure what to test? "aitd plan --site ${config.site}" drafts a measurement plan.`);
   if (opts.scripted) {
     const unscripted = journeys.filter((j) => !j.steps?.length && !j.incomplete).map((j) => j.id);
     if (unscripted.length) throw new Error(`Journeys without fixed steps can't be replayed with --scripted: ${unscripted.join(", ")}.`);
   }
 
+  if (against) {
+    const notChecked = plan.events.filter((e) => Array.isArray(e.journeys) && !e.journeys.some((j) => journeys.some((jj) => jj.id === j))).length;
+    log(`Checking against plan ${against.label}: ${journeys.length} ${journeys.length === 1 ? "journey" : "journeys"}${notChecked ? `, ${notChecked} planned ${notChecked === 1 ? "event" : "events"} not checked in this run` : ""}`);
+    for (const j of journeys) {
+      const expected = plan.events.filter((e) => !e.journeys || e.journeys.includes(j.id)).map((e) => e.name);
+      log(`  - ${j.id}: ${j.goal ?? "fixed steps"}${expected.length ? ` [${[...new Set(expected)].join(", ")}]` : ""}`);
+    }
+  }
+
   const provider = useAi ? await createProvider({ name: opts.provider ?? config.provider, model: opts.model ?? config.model, baseUrl: opts.baseUrl ?? config.base_url }) : null;
   if (provider) log(`Using ${provider.name} (${provider.model})`);
 
@@ -116,8 +130,8 @@ export async function runAudit(opts) {
     explained = await explainFindings({ findings, plan, runs, gtmContainer, provider, lang, log });
   }
 
-  const outDir = path.resolve(opts.outDir ?? defaultOutDir());
-  const reportPath = await writeReports({ outDir, config, plan, runs, findings, explained, lang, branding: opts.branding ?? config.branding !== false });
+  const outDir = path.resolve(opts.outDir ?? (await newRunDir(opts.dataDir, config.site)).dir);
+  const reportPath = await writeReports({ outDir, config, plan, runs, findings, explained, lang, against, branding: opts.branding ?? config.branding !== false });
   const counts = summarize(groupFindings(findings));
-  return { runs, findings, explained, counts, reportPath, outDir, lang, ...(saveError ? { saveError } : {}) };
+  return { journeys, plan, runs, findings, explained, counts, reportPath, outDir, lang, ...(against ? { againstId: against.id } : {}), ...(saveError ? { saveError } : {}) };
 }

package/src/checks.js

@@ -68,6 +68,17 @@ export function hasParam(hit, name) {
   return [name, ...(PARAM_ALIASES[name] ?? [])].some((n) => hit.params?.[n] !== undefined && hit.params[n] !== "");
 }
 
+/** A hit's parameter under its own name or the first common alias it carries. */
+function paramOf(hit, name) {
+  for (const n of [name, ...(PARAM_ALIASES[name] ?? [])]) {
+    if (hit.params?.[n] !== undefined && hit.params[n] !== "") return hit.params[n];
+  }
+  return undefined;
+}
+
+const isPurchase = (hit) => canonicalEvent(hit.name) === "purchase";
+const EMPTY_LIST = /^\s*(\[\s*\])?\s*$/;
+
 /** The page load a hit came from: GA4's page load id (_p) when it has one, else the page address. */
 function pageOf(hit) {
   try {
@@ -99,7 +110,7 @@ function expectedIn(planEvent, journeyId) {
   return !planEvent.journeys || planEvent.journeys.includes(journeyId);
 }
 
-function isConsentCommand(entry, kind) {
+export function isConsentCommand(entry, kind) {
   return Array.isArray(entry.value) && entry.value[0] === "consent" && entry.value[1] === kind;
 }
 
@@ -203,6 +214,62 @@ export function checkRun(plan, run, { lang = "en" } = {}) {
     });
   }
 
+  // Purchase values: a value that is 0, negative or not a number, a currency that isn't an ISO
+  // code, and an empty items list (reported once per platform and event).
+  const purchaseReported = new Set();
+  const reportPurchase = (hit, check, severity, detail) => {
+    const k = `${check}|${key(hit.platform, hit.name)}`;
+    if (purchaseReported.has(k)) return;
+    purchaseReported.add(k);
+    findings.push({ ...base, severity, check, platform: hit.platform, event: hit.name, step: stepLabel(hit.step), detail, evidence: JSON.stringify(hit.params) });
+  };
+  const purchases = run.hits.filter(isPurchase);
+  for (const hit of purchases) {
+    const value = paramOf(hit, "value");
+    if (value !== undefined) {
+      const n = Number(value);
+      if (!Number.isFinite(n) || String(value).trim() === "") reportPurchase(hit, "purchase_value_invalid", "broken", d.purchaseValueNaN(hit.platform, hit.name, value));
+      else if (n <= 0) reportPurchase(hit, "purchase_value_invalid", "broken", d.purchaseValueZero(hit.platform, hit.name, value));
+    }
+    const currency = paramOf(hit, "currency");
+    if (currency !== undefined && !/^[A-Z]{3}$/.test(currency)) reportPurchase(hit, "purchase_currency_invalid", "broken", d.purchaseCurrency(hit.platform, hit.name, currency));
+    // GA4 sends items as pr1, pr2...; Meta as contents or content_ids. Items left out of a GA4
+    // purchase count as empty, unless the plan requires them and missing_params already says so.
+    const listed = ["items", "contents", "content_ids"].filter((n) => hit.params?.[n] !== undefined);
+    const requiresItems = planEventFor(hit)?.required_params?.includes("items");
+    const empty = listed.length
+      ? listed.every((n) => EMPTY_LIST.test(hit.params[n]))
+      : hit.platform === "ga4" && !requiresItems && !hasParam(hit, "items");
+    if (empty) reportPurchase(hit, "purchase_items_empty", "warning", d.purchaseItemsEmpty(hit.platform, hit.name));
+  }
+
+  // GA4 and Meta reporting the same order with a different value or currency. Purchases are paired
+  // by order ID; without IDs, a run with one purchase on each platform is taken as one order.
+  const ga4Buys = purchases.filter((h) => h.platform === "ga4");
+  const metaBuys = purchases.filter((h) => h.platform === "meta");
+  const orderId = (h) => paramOf(h, "transaction_id");
+  const pairs = [];
+  for (const g of ga4Buys) {
+    const m = orderId(g) !== undefined && metaBuys.find((h) => orderId(h) === orderId(g));
+    if (m) pairs.push([g, m]);
+  }
+  if (!pairs.length && ga4Buys.length === 1 && metaBuys.length === 1) {
+    const [g, m] = [ga4Buys[0], metaBuys[0]];
+    if (orderId(g) === undefined || orderId(m) === undefined) pairs.push([g, m]);
+  }
+  const mismatchSeen = new Set();
+  for (const [g, m] of pairs) {
+    const [gv, mv] = [paramOf(g, "value"), paramOf(m, "value")];
+    const [gc, mc] = [paramOf(g, "currency"), paramOf(m, "currency")];
+    const diffs = [];
+    if (gv !== undefined && mv !== undefined && Number.isFinite(Number(gv)) && Number.isFinite(Number(mv)) && Math.abs(Number(gv) - Number(mv)) > 0.005) diffs.push(["value", gv, mv]);
+    if (gc !== undefined && mc !== undefined && gc.toUpperCase() !== mc.toUpperCase()) diffs.push(["currency", gc, mc]);
+    const k = `${orderId(g) ?? ""}|${diffs.map((x) => x.join("=")).join(",")}`;
+    if (!diffs.length || mismatchSeen.has(k)) continue;
+    mismatchSeen.add(k);
+    findings.push({ ...base, severity: "warning", check: "purchase_mismatch", platform: "meta", event: m.name, step: stepLabel(m.step), detail: d.purchaseMismatch(orderId(g) ?? orderId(m), diffs), evidence: JSON.stringify({ ga4: g.params, meta: m.params }) });
+  }
+
   // Server-side tagging. Only what the browser can see: a GA4 hit to a server container, and requests
   // to Stape or Elevar. Meta's and TikTok's server-side copies never pass through the browser.
   const serverHits = run.hits.filter((h) => h.delivery === "server");
@@ -377,3 +444,58 @@ export function groupFindings(findings) {
   }
   return [...groups.values()].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
 }
+
+const WRONG_VALUE_CHECKS = new Set(["purchase_value_invalid", "purchase_currency_invalid", "purchase_items_empty", "purchase_mismatch"]);
+export const PLAN_BUCKETS = ["implemented", "missing", "missing_params", "wrong_values", "unplanned", "not_checked"];
+
+/**
+ * Sorts every planned event into one bucket from the runs and the findings checkRun gave them:
+ * implemented, missing, missing_params, wrong_values or not_checked, plus one unplanned entry per
+ * event that fired but is not in the plan. Coverage = implemented / planned events that were checkable.
+ * @param {Plan} plan
+ * @param {any[]} runs
+ * @param {Finding[]} findings
+ */
+export function planCheck(plan, runs, findings) {
+  const events = (plan?.events ?? []).map((e) => ({ ...e, platform: String(e.platform ?? "").toLowerCase() }));
+  const entries = [];
+  for (const ev of events) {
+    const walked = runs.filter((r) => expectedIn(ev, r.journeyId) && (!r.providers || r.providers.includes(ev.platform)));
+    const entry = { platform: ev.platform, event: ev.name, bucket: "not_checked", journeys: [...new Set(walked.map((r) => r.journeyId))] };
+    if (walked.length) {
+      const own = findings.filter((f) => f.event && walked.some((r) => r.journeyId === f.journey && r.viewport === f.viewport) && hitMatchesEvent(ev, { platform: f.platform, name: f.event }));
+      const params = own.filter((f) => f.check === "missing_params");
+      const values = own.filter((f) => WRONG_VALUE_CHECKS.has(f.check));
+      const fired = walked.some((r) => r.hits.some((h) => hitMatchesEvent(ev, h)));
+      if (params.length) entry.bucket = "missing_params";
+      else if (values.length) entry.bucket = "wrong_values";
+      else entry.bucket = fired ? "implemented" : "missing";
+      const details = [...new Set([...params, ...values].map((f) => f.detail))];
+      if (details.length) entry.details = details;
+    }
+    entries.push(entry);
+  }
+  // Unplanned events, from the runs whose unplanned_events finding survived the --event filter.
+  const seen = new Set();
+  for (const r of runs) {
+    if (!findings.some((f) => f.check === "unplanned_events" && f.journey === r.journeyId && f.viewport === r.viewport)) continue;
+    for (const h of r.hits) {
+      if (events.some((e) => hitMatchesEvent(e, h)) || seen.has(key(h.platform, h.name))) continue;
+      seen.add(key(h.platform, h.name));
+      entries.push({ platform: h.platform, event: h.name, bucket: "unplanned", journeys: [r.journeyId] });
+    }
+  }
+  const score = (list) => {
+    const planned = list.filter((e) => e.bucket !== "unplanned");
+    const checkable = planned.filter((e) => e.bucket !== "not_checked").length;
+    const implemented = planned.filter((e) => e.bucket === "implemented").length;
+    return { implemented, checkable, not_checked: planned.length - checkable, percent: checkable ? Math.round((implemented / checkable) * 100) : null };
+  };
+  const platforms = [...new Set(entries.filter((e) => e.bucket !== "unplanned").map((e) => e.platform))];
+  const counts = Object.fromEntries(PLAN_BUCKETS.map((b) => [b, entries.filter((e) => e.bucket === b).length]));
+  return {
+    coverage: { ...score(entries), platforms: Object.fromEntries(platforms.map((p) => [p, score(entries.filter((e) => e.platform === p))])) },
+    counts,
+    events: entries,
+  };
+}

package/src/cli.js

@@ -3,74 +3,14 @@ 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 { replaySavedSite } from "./replay.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";
 
 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.
-
-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() {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
@@ -83,6 +23,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 },
@@ -103,7 +44,13 @@ async function main() {
       reports: { type: "string" },
       "public-url": { type: "string" },
       "save-site": { type: "string" },
+      "save-steps": { type: "string" },
       update: { type: "boolean", default: false },
+      "data-dir": { type: "string" },
+      against: { type: "string" },
+      from: { type: "string" },
+      format: { type: "string" },
+      force: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
       version: { type: "boolean", short: "v", default: false },
     },
@@ -141,19 +88,75 @@ 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");
+    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, 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 {
@@ -163,6 +166,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,
@@ -170,7 +175,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,
@@ -180,7 +185,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),
   });
 
@@ -193,6 +200,44 @@ async function main() {
     if (levels.slice(0, threshold + 1).some((l) => result.counts[l] > 0)) process.exitCode = 1;
   }
   if (result.saveError) process.exitCode = 1;
+  if (values["save-steps"]) {
+    try {
+      const { saved, skipped } = await writeSavedSteps(values["save-steps"], { site: loaded.config.site, plan: result.plan, journeys: result.journeys, runs: result.runs });
+      if (saved.length) console.log(`Saved the steps of ${saved.join(", ")} in ${values["save-steps"]}. Repeat them with: aitd run --config ${values["save-steps"]} --scripted --no-ai`);
+      if (skipped.length) console.log(`No steps to save for ${skipped.join(", ")}.`);
+    } catch (err) {
+      console.log(`Could not save the steps in ${values["save-steps"]}: ${err.message}`);
+      process.exitCode = 1;
+    }
+  }
+}
+
+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) => {