@analitikisler/ai-tag-debugger 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.9.0 (2026-10-15)
+
+- `aitd run ... --save-steps <file>` writes the steps each journey took into `journeys[].steps` of that config file (creating it if needed, and adding the run's plan when the config has none). A later `aitd 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 its first viewport.
+- New purchase checks: a purchase sent with a value that is 0, negative or not a number (`purchase_value_invalid`), a currency that isn't a 3-letter ISO code such as USD (`purchase_currency_invalid`), or no items (`purchase_items_empty`). GA4 and Meta reporting the same order with a different value or currency is flagged as `purchase_mismatch`; purchases are paired by order ID, or taken as one order when the journey has a single purchase on each.
+
+## 0.8.2 (2026-10-15)
+
+- A journey that fails with an error, such as the AI provider's API refusing a request or the browser crashing, no longer ends the whole audit. That journey is marked unfinished with the error as its note, what it captured until then is kept, the other journeys still run, and the report is written. This applies to the CLI and to `run_audit` over MCP.
+- A Consent Mode default pushed after the first Google hit is now reported as late (`consent_default_late`) when both happen on the same step, such as the start page. The check used to compare only step numbers, so it missed this. Only Google hits count, since Consent Mode only governs Google tags.
+- An unknown viewport, given with `--viewport` or in the config's `viewports`, now stops the audit at once with a message listing the allowed values (desktop, mobile). Before, it failed only when the browser started for that journey, after the model was set up and earlier journeys had run.
+- `ai-tag-debugger --version` (or `aitd -v`) prints the installed version.
+- New short command `aitd`, an alias for `ai-tag-debugger` installed alongside it.
+- For contributors: `npm run setup` checks the Node version, installs the dependencies and Chromium, and says whether an AI provider key is set. A dev container (`.devcontainer/devcontainer.json`) runs it, so VS Code and Codespaces open the repository ready to run.
+
 ## 0.8.1 (2026-10-15)
 
 - A run with no AI provider key set now stops at once with a message naming the keys to set and the `--scripted --no-ai` option, instead of starting the browser and failing at the first step with the SDK's "Could not resolve authentication method".

package/README.md

@@ -40,6 +40,10 @@ Manual tag QA catches this, but it's tedious, so it rarely happens after every r
 |---|---|
 | Missing events | `purchase` never fired on the checkout journey |
 | Missing parameters | `purchase` sent without `value` and `currency` on mobile |
+| Invalid purchase value | `purchase` sent with `value` `0`, a negative number or text such as `"free"` |
+| Invalid purchase currency | `purchase` sent with currency `usd` or `TL` instead of a 3-letter ISO code such as `USD` or `TRY` |
+| Empty purchase items | `purchase` sent with an empty `items` list |
+| Purchase mismatch | GA4 sends `value` 120 and Meta sends 115 for the same order ID |
 | Duplicates | `add_to_cart` sent twice by one click |
 | Consent | Meta `PageView` fired before the visitor accepted cookies, Consent Mode default missing or set too late, Consent Mode v2 signals (`ad_user_data`, `ad_personalization`) missing, tracking cookies set before consent, tags or cookies still active after the `decline_cookies` journey rejects the banner, a reject button that does nothing |
 | Personal data | An email address sent to an ad platform in plain text |
@@ -110,6 +114,8 @@ export ANTHROPIC_API_KEY=...                # or OPENAI_API_KEY, or GEMINI_API_K
 ai-tag-debugger run --site https://staging.yourshop.com --journey add_to_cart --headed
 ```
 
+The global install also adds `aitd`, a short alias: `aitd run --site … --journey add_to_cart` does the same.
+
 Or run it without installing: `npx -y @analitikisler/ai-tag-debugger run --site … --journey add_to_cart`.
 
 Run `ai-tag-debugger --help` to see every command and option, such as `--providers`, `--scripted` and `--no-ai`.
@@ -168,7 +174,7 @@ Each browsing step is one model call, so usage grows with **journeys × viewport
 - **Cap the steps.** `--max-steps 15` stops a journey that wanders.
 - **Expect bigger pages to cost more.** Each step sends the page view (up to 250 elements and 3,000 characters of text) to the model, so busy pages use more tokens per step than simple ones.
 - **Use `--events`** to keep the report focused. It doesn't shorten browsing, so it barely changes usage.
-- **Replay without AI.** After one AI run, copy the steps into `journeys[].steps` and use `--scripted` (with `--no-ai` for zero model calls) on every deploy.
+- **Replay without AI.** After one AI run, add `--save-steps <file>` to save its steps, then run that config with `--scripted --no-ai` on every deploy. See [Save the steps and replay them without AI](#save-the-steps-and-replay-them-without-ai).
 - **Use a chat app.** Over MCP, the chat app's own model does the browsing, so no API key is used at all.
 
 ### Check a new version against saved sites
@@ -184,6 +190,17 @@ npx @analitikisler/ai-tag-debugger replay saved/*
 
 The first run's findings become the expected ones. When a change is right, for example a false alarm that is fixed, `replay --update` makes the new findings the expected ones. Use it to check a new version of the tool against sites you know, or a site change against its last good run. A saved site is usually a few MB. It leaves out tracking requests, images and video, HttpOnly and login cookies and the cookies the browser sent, authorization headers, form data, and requests with an email or other user data in their address. It still holds the site's pages and scripts, so keep sites you don't own out of public repositories.
 
+### Save the steps and replay them without AI
+
+`--save-steps <file>` writes the steps each journey took into `journeys[].steps` of a config file. It creates the file if it's missing, and it also saves the run's plan when the config has none. The same config then repeats the journey with no AI model and no API key:
+
+```bash
+ai-tag-debugger run --site https://www.yourshop.com --journey purchase --save-steps ai-tag-debugger.config.json
+ai-tag-debugger run --config ai-tag-debugger.config.json --scripted --no-ai
+```
+
+When a journey ran on both viewports, only the first viewport's steps are kept. Keep the config in your repository and run the second command on every deploy to check the same journey without any model calls.
+
 ## Configure your site
 
 `ai-tag-debugger.config.json`:
@@ -246,12 +263,14 @@ ai-tag-debugger run [--site <url>] [--config <file>] [--journey <id>] [--goal "<
                 [--max-steps <n>] [--out <dir>] [--viewport desktop|mobile] [--providers <list>]
                 [--provider anthropic|openai|gemini|openai-compatible] [--model <id>] [--base-url <url>]
                 [--lang en|tr] [--allow-host <host>] [--keep-bodies] [--scripted] [--no-ai] [--fail-on broken|risk|warning|never] [--headed]
-                [--save-site <dir>]
+                [--save-site <dir>] [--save-steps <file>]
 ai-tag-debugger replay <dir>... [--update] [--out <dir>]
 ai-tag-debugger mcp [--http] [--port <n>] [--host <addr>] [--token <secret>] [--public-url <https url>] [--reports <dir>]
                 [--allow-private-network]
 ```
 
+`aitd` is a short alias for `ai-tag-debugger` and takes the same commands and options.
+
 The exit code is `1` when findings reach `--fail-on` (default `broken`), so it can gate a deploy. See [`examples/github-actions/ai-tag-debugger.yml`](examples/github-actions/ai-tag-debugger.yml) for running it after every deployment.
 
 Output:
@@ -358,9 +377,12 @@ A hosted server, so you don't need a tunnel, is part of the [Analitik İşler](h
 ## Development
 
 ```bash
-npm test   # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
+npm run setup   # checks Node, installs the dependencies and Chromium, says whether an AI provider key is set
+npm test        # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
 ```
 
+The repository also has a dev container (`.devcontainer/devcontainer.json`). Open it in VS Code with the Dev Containers extension, or in GitHub Codespaces, and it runs `npm run setup` for you, Chromium's system libraries included. To use an AI model there, add your key as a Codespaces secret or export it in the container's terminal.
+
 The end-to-end tests use fake model clients, so they run without an API key.
 
 ## Hosted version

package/README.tr.md

@@ -40,6 +40,10 @@ Tag'leri elle test etmek bunu yakalar, ama zahmetli olduğu için her sürümden
 |---|---|
 | Eksik event'ler | `purchase`, ödeme senaryosunda hiç gönderilmedi |
 | Eksik parametreler | `purchase`, mobilde `value` ve `currency` olmadan gönderildi |
+| Geçersiz satın alma değeri | `purchase`, `value` olarak `0`, negatif bir sayı ya da `"ücretsiz"` gibi bir metinle gönderildi |
+| Geçersiz satın alma para birimi | `purchase`, para birimi `usd` ya da `TL` olarak gönderildi; `USD` ya da `TRY` gibi 3 harfli ISO kodu bekleniyor |
+| Boş satın alma ürünleri | `purchase`, boş bir `items` listesiyle gönderildi |
+| Satın alma uyuşmazlığı | Aynı sipariş numarası için GA4 `value` 120, Meta 115 gönderdi |
 | Tekrar eden event'ler | `add_to_cart` tek tıklamada iki kez gönderildi |
 | Çerez onayı | Meta `PageView`, ziyaretçi çerezleri kabul etmeden gönderildi; Consent Mode varsayılanı yok ya da çok geç ayarlanmış, Consent Mode v2 sinyalleri (`ad_user_data`, `ad_personalization`) eksik, onaydan önce yazılan izleme çerezleri, `decline_cookies` yolculuğu bandı reddettikten sonra hâlâ çalışan etiketler ya da çerezler, işe yaramayan reddet düğmesi |
 | Kişisel veri | Bir e-posta adresi reklam platformuna açık metin olarak gönderildi |
@@ -110,6 +114,8 @@ export ANTHROPIC_API_KEY=...                # or OPENAI_API_KEY, or GEMINI_API_K
 ai-tag-debugger run --site https://staging.yourshop.com --journey add_to_cart --headed
 ```
 
+Global kurulum kısa bir takma ad olan `aitd` komutunu da ekler: `aitd run --site … --journey add_to_cart` aynı işi yapar.
+
 Ya da kurmadan çalıştırın: `npx -y @analitikisler/ai-tag-debugger run --site … --journey add_to_cart`.
 
 Tüm komutları ve seçenekleri (`--providers`, `--scripted`, `--no-ai` gibi) görmek için `ai-tag-debugger --help` çalıştırın.
@@ -170,7 +176,7 @@ Her gezinme adımı bir model çağrısıdır. Yani kullanım **senaryo × ekran
 - **Adım sayısını sınırlayın.** `--max-steps 15`, yolunu kaybeden bir senaryoyu durdurur.
 - **Büyük sayfaların daha pahalı olduğunu unutmayın.** Her adım modele sayfanın görünümünü (en fazla 250 öğe ve 3.000 karakter metin) gönderir. Bu yüzden kalabalık sayfalar adım başına daha fazla token kullanır.
 - **Raporu odaklı tutmak için `--events` kullanın.** Gezinmeyi kısaltmadığı için kullanımı pek değiştirmez.
-- **Yapay zekâ olmadan tekrar oynatın.** Bir yapay zekâ çalıştırmasından sonra adımları `journeys[].steps` içine kopyalayın ve her deploy'da `--scripted` (hiç model çağrısı olmaması için `--no-ai` ile birlikte) kullanın.
+- **Yapay zekâ olmadan tekrar oynatın.** Bir yapay zekâ çalıştırmasından sonra `--save-steps <dosya>` ile adımları kaydedin, ardından her deploy'da o ayar dosyasıyla `--scripted --no-ai` kullanın. Ayrıntılar için [Adımları kaydedin ve yapay zekâ olmadan tekrar oynatın](#adımları-kaydedin-ve-yapay-zekâ-olmadan-tekrar-oynatın) bölümüne bakın.
 - **Bir yapay zekâ asistanı kullanın.** MCP üzerinden gezinmeyi asistanın kendi modeli yapar, hiç API anahtarı kullanılmaz.
 
 ### Yeni bir sürümü kaydedilmiş sitelerle karşılaştırın
@@ -186,6 +192,17 @@ npx @analitikisler/ai-tag-debugger replay saved/*
 
 İlk çalıştırmanın bulguları beklenen bulgular olur. Bir değişiklik doğruysa (örneğin düzeltilmiş bir yanlış alarm), `replay --update` yeni bulguları beklenen bulgular yapar. Aracın yeni bir sürümünü bildiğiniz sitelerle ya da bir site değişikliğini son sağlıklı çalıştırmayla karşılaştırmak için kullanın. Kaydedilmiş bir site genellikle birkaç MB'tır. İzleme isteklerini, görselleri ve videoları, HttpOnly ve oturum açma çerezlerini ve tarayıcının gönderdiği çerezleri, yetkilendirme başlıklarını, form verilerini ve adresinde e-posta ya da başka kullanıcı verisi olan istekleri içermez. Yine de sitenin sayfalarını ve betiklerini içerdiği için size ait olmayan siteleri herkese açık depolara koymayın.
 
+### Adımları kaydedin ve yapay zekâ olmadan tekrar oynatın
+
+`--save-steps <dosya>`, her senaryonun izlediği adımları bir ayar dosyasındaki `journeys[].steps` alanına yazar. Dosya yoksa oluşturulur; ayar dosyasında plan yoksa çalıştırmanın planı da kaydedilir. Aynı ayar dosyası, hiçbir yapay zekâ modeli ve API anahtarı olmadan senaryoyu tekrar çalıştırır:
+
+```bash
+ai-tag-debugger run --site https://www.magazaniz.com --journey purchase --save-steps ai-tag-debugger.config.json
+ai-tag-debugger run --config ai-tag-debugger.config.json --scripted --no-ai
+```
+
+Bir senaryo iki ekran boyutunda çalıştıysa yalnızca ilk ekran boyutunun adımları tutulur. Ayar dosyasını depoda saklayın ve ikinci komutu her deploy'da çalıştırarak aynı senaryoyu hiçbir model çağrısı yapmadan kontrol edin.
+
 ## Sitenizi ayarlayın
 
 `ai-tag-debugger.config.json`:
@@ -246,12 +263,14 @@ ai-tag-debugger run [--site <url>] [--config <file>] [--journey <id>] [--goal "<
                 [--max-steps <n>] [--out <dir>] [--viewport desktop|mobile] [--providers <list>]
                 [--provider anthropic|openai|gemini|openai-compatible] [--model <id>] [--base-url <url>]
                 [--lang en|tr] [--allow-host <host>] [--keep-bodies] [--scripted] [--no-ai] [--fail-on broken|risk|warning|never] [--headed]
-                [--save-site <dir>]
+                [--save-site <dir>] [--save-steps <file>]
 ai-tag-debugger replay <dir>... [--update] [--out <dir>]
 ai-tag-debugger mcp [--http] [--port <n>] [--host <addr>] [--token <secret>] [--public-url <https url>] [--reports <dir>]
                 [--allow-private-network]
 ```
 
+`aitd`, `ai-tag-debugger` için kısa bir takma addır ve aynı komut ve seçenekleri alır.
+
 Bulgular `--fail-on` seviyesine (varsayılan `broken`) ulaştığında çıkış kodu `1` olur, böylece bir deploy'u durdurabilir. Her deploy sonrası çalıştırmak için [`examples/github-actions/ai-tag-debugger.yml`](examples/github-actions/ai-tag-debugger.yml) örneğine bakın.
 
 Çıktılar:
@@ -358,9 +377,12 @@ Tünele gerek kalmayan, hazır bir adresle barındırılan sunucu, [Analitik İ
 ## Geliştirme
 
 ```bash
-npm test   # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
+npm run setup   # checks Node, installs the dependencies and Chromium, says whether an AI provider key is set
+npm test        # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
 ```
 
+Depoda bir dev container (`.devcontainer/devcontainer.json`) da var. Depoyu VS Code'da Dev Containers eklentisiyle ya da GitHub Codespaces'te açtığınızda `npm run setup` sizin için çalışır ve Chromium'un sistem kütüphanelerini de kurar. Orada bir yapay zekâ modeli kullanmak için anahtarınızı Codespaces secret olarak ekleyin ya da container'ın terminalinde export edin.
+
 Uçtan uca testler sahte model istemcileri kullanır, bu yüzden API anahtarı olmadan çalışır.
 
 ## Barındırılan sürüm

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
   "mcpName": "io.github.analitikisler/ai-tag-debugger",
-  "version": "0.8.1",
+  "version": "0.9.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": {
-    "ai-tag-debugger": "src/cli.js"
+    "ai-tag-debugger": "src/cli.js",
+    "aitd": "src/cli.js"
   },
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
+    "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"

package/src/agent.js

@@ -203,12 +203,27 @@ export async function runJourney(config, journey, viewport, opts = {}) {
       throw err;
     });
     return { ...collect(session, journey, viewport), ...outcome, cookies: await session.cookies() };
+  } catch (err) {
+    // The model's API, the browser or the site can fail in many ways. That ends this journey, not the run,
+    // and what was captured until then is kept.
+    return { ...collect(session, journey, viewport), completed: false, note: journeyError(err) };
   } finally {
     if (opts.saveSite) opts.log?.("  Writing the recording…");
     await session.close();
   }
 }
 
+/** The note of a journey that ended with an error. */
+export const journeyError = (err) => `The journey stopped with an error: ${err?.message ?? err}`;
+
+/** A journey that failed before anything was captured, so the report can still list it. */
+export function failedRun(journey, viewport, err, providers) {
+  return {
+    journeyId: journey.id, viewport, completed: false, note: journeyError(err), hits: [], steps: [], consentStep: null, rejectStep: null,
+    cookieLog: [], dataLayerLog: [], network: [], providers, skipped: {}, bodyBudgetStep: null, startedAt: Date.now(), pageErrors: [],
+  };
+}
+
 export function collect(session, journey, viewport) {
   return {
     journeyId: journey.id,

package/src/audit.js

@@ -2,7 +2,8 @@
 // Shared by the CLI and the MCP server's run_audit tool.
 import { readFile, mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { runJourney } from "./agent.js";
+import { failedRun, runJourney } from "./agent.js";
+import { VIEWPORTS } from "./browser.js";
 import { checkRun, groupFindings, summarize } from "./checks.js";
 import { explainFindings, renderCsv, renderHtml, renderMarkdown } from "./report.js";
 import { LANGUAGES, messages } from "./i18n.js";
@@ -70,6 +71,10 @@ export async function runAudit(opts) {
   const { journeys, plan } = planRun({ config, plan: opts.plan, picks: opts.journeys, goals: opts.goals, events });
   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 (opts.scripted) {
     const unscripted = journeys.filter((j) => !j.steps?.length && !j.incomplete).map((j) => j.id);
@@ -84,7 +89,9 @@ export async function runAudit(opts) {
   for (const journey of journeys) {
     for (const viewport of viewports) {
       log(`\n▶ ${journey.id} (${viewport})`);
-      const run = await runJourney(config, journey, viewport, { scripted: opts.scripted, provider, maxSteps: opts.maxSteps, headed: opts.headed, lang, log, saveSite: opts.saveSite, replaySite: opts.replaySite });
+      // runJourney keeps its own errors in the run. This catches the rest, such as a browser that won't close,
+      // so one journey can't cost the report of the others.
+      const run = await runJourney(config, journey, viewport, { scripted: opts.scripted, provider, maxSteps: opts.maxSteps, headed: opts.headed, lang, log, saveSite: opts.saveSite, replaySite: opts.replaySite }).catch((err) => failedRun(journey, viewport, err, config.providers));
       log(`  ${run.completed ? "✓" : "✗"} ${run.note} · ${run.hits.length} tracking hits captured`);
       runs.push(run);
     }
@@ -112,5 +119,5 @@ export async function runAudit(opts) {
   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 counts = summarize(groupFindings(findings));
-  return { runs, findings, explained, counts, reportPath, outDir, lang, ...(saveError ? { saveError } : {}) };
+  return { journeys, plan, runs, findings, explained, counts, reportPath, outDir, lang, ...(saveError ? { saveError } : {}) };
 }

package/src/checks.js

@@ -5,6 +5,11 @@ import { messages } from "./i18n.js";
 import { isOwnAddress } from "./redact.js";
 
 const NON_GOOGLE_AD_PLATFORMS = new Set(["meta", "tiktok"]);
+const GOOGLE_PLATFORMS = new Set(["ga4", "google_ads"]);
+
+/** Whether a happened before b: an earlier step, or the same step and an earlier time when both have one. */
+const sentBefore = (a, b) => a.step < b.step || (a.step === b.step && a.t != null && b.t != null && a.t < b.t);
+
 const EMAIL = /[A-Z0-9._%+-]+(@|%40)[A-Z0-9.-]+\.[A-Z]{2,}/gi;
 // Consent Mode v2 added two signals to ad_storage and analytics_storage. Google requires them for EEA/UK traffic.
 const V2_SIGNALS = ["ad_user_data", "ad_personalization"];
@@ -63,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 {
@@ -198,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");
@@ -222,12 +294,13 @@ export function checkRun(plan, run, { lang = "en" } = {}) {
 
   // Consent.
   const granted = consentGrantedStep(run);
-  const firstHitStep = run.hits.length ? Math.min(...run.hits.map((h) => h.step)) : null;
+  // Consent Mode only governs Google tags. Within one step, the push and hit times decide which came first.
+  const firstGoogleHit = run.hits.filter((h) => GOOGLE_PLATFORMS.has(h.platform)).reduce((a, h) => (!a || sentBefore(h, a) ? h : a), null);
   if (plan.consent_mode) {
     const defaultEntry = run.dataLayerLog.find((e) => isConsentCommand(e, "default"));
     if (!defaultEntry) {
       findings.push({ ...base, severity: "risk", check: "consent_default_missing", detail: d.consentDefaultMissing() });
-    } else if (firstHitStep !== null && defaultEntry.step > firstHitStep) {
+    } else if (firstGoogleHit && sentBefore(firstGoogleHit, defaultEntry)) {
       findings.push({ ...base, severity: "risk", check: "consent_default_late", detail: d.consentDefaultLate() });
     }
   }

package/src/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { loadConfig, runAudit } from "./audit.js";
@@ -6,7 +7,9 @@ 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 { replaySavedSite, writeSavedSteps } from "./replay.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.
 
@@ -46,6 +49,9 @@ Run options:
   --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).
@@ -61,6 +67,9 @@ MCP options:
   --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.`;
@@ -97,11 +106,17 @@ async function main() {
       reports: { type: "string" },
       "public-url": { type: "string" },
       "save-site": { type: "string" },
+      "save-steps": { type: "string" },
       update: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
     },
   });
   const command = positionals[0];
+  if (values.version) {
+    console.log(VERSION);
+    return;
+  }
 
   if (command === "mcp" && !values.help) {
     const { startMcp } = await import("./mcp.js");
@@ -182,6 +197,16 @@ 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;
+    }
+  }
 }
 
 main().catch((err) => {

package/src/i18n.js

@@ -121,6 +121,11 @@ const en = {
     missingEventEarly: (name) => `${q(name)} was not seen, but the journey stopped early, so this may not be a tracking bug.`,
     missingParams: (name, params) => `${q(name)} was sent without ${params.map(q).join(", ")}.`,
     duplicate: (name, n) => `${q(name)} was sent ${n} times by one action, which inflates counts and conversions.`,
+    purchaseValueZero: (platform, name, v) => `${platform} ${q(name)} was sent with value ${q(v)}. A purchase worth 0 or less adds no revenue, and ad platforms can't optimize bids on it.`,
+    purchaseValueNaN: (platform, name, v) => `${platform} ${q(name)} was sent with value ${q(v)}, which is not a number, so the revenue is lost. Send a plain number such as 49.90, with no currency sign or thousands separator.`,
+    purchaseCurrency: (platform, name, c) => `${platform} ${q(name)} was sent with currency ${q(c)}, which is not a 3-letter ISO 4217 code in capitals (such as USD, EUR or TRY). Platforms may drop the revenue or convert it wrongly.`,
+    purchaseItemsEmpty: (platform, name) => `${platform} ${q(name)} was sent with no items, so product and item reports get nothing for this order.`,
+    purchaseMismatch: (id, diffs) => `GA4 and Meta reported ${id ? `order ${q(id)}` : "the purchase"} differently: ${diffs.map(([f, g, m]) => `${f} ${q(g)} in GA4 and ${q(m)} in Meta`).join("; ")}. One of the tags reads the wrong data.`,
     serverSide: (platform, server, browser) => `${platform}: ${server.map(q).join(", ")} ${server.length === 1 ? "was" : "were"} sent to a server container on the site's own domain (server-side tagging)${browser.length ? `; ${browser.map(q).join(", ")} went directly from the browser` : ""}. Server-side copies of Meta and TikTok events never pass through the browser, so they can't be seen here.`,
     dedupIdMissing: (platform, name) => `${platform} ${q(name)} was sent from the browser without an event ID, while a server-side setup was seen on this site. If the server also sends this event, ${platform} can't match the two and counts it twice.`,
     consentDefaultMissing: () => "No Google Consent Mode default command (gtag('consent', 'default', ...)) was found in the dataLayer.",
@@ -263,6 +268,11 @@ const tr = {
     missingEventEarly: (name) => `${q(name)} görülmedi, ancak yolculuk erken durduğu için bu bir izleme hatası olmayabilir.`,
     missingParams: (name, params) => `${q(name)} olayı ${params.map(q).join(", ")} ${params.length > 1 ? "parametreleri" : "parametresi"} olmadan gönderildi.`,
     duplicate: (name, n) => `${q(name)} tek bir işlemde ${n} kez gönderildi; bu da sayıları ve dönüşümleri şişirir.`,
+    purchaseValueZero: (platform, name, v) => `${platform} ${q(name)} ${q(v)} değeriyle gönderildi. 0 veya daha düşük değerli bir satın alma gelire eklenmez ve reklam platformları teklifleri buna göre optimize edemez.`,
+    purchaseValueNaN: (platform, name, v) => `${platform} ${q(name)} sayı olmayan ${q(v)} değeriyle gönderildi, bu yüzden gelir kayboluyor. Para birimi işareti veya binlik ayırıcı olmadan 49.90 gibi düz bir sayı gönderin.`,
+    purchaseCurrency: (platform, name, c) => `${platform} ${q(name)} ${q(c)} para birimiyle gönderildi; bu, büyük harfli 3 harfli bir ISO 4217 kodu değil (USD, EUR veya TRY gibi). Platformlar geliri atabilir veya yanlış çevirebilir.`,
+    purchaseItemsEmpty: (platform, name) => `${platform} ${q(name)} ürün listesi boş gönderildi, bu yüzden ürün raporları bu siparişten veri alamaz.`,
+    purchaseMismatch: (id, diffs) => `GA4 ve Meta ${id ? `${q(id)} siparişini` : "satın almayı"} farklı bildirdi: ${diffs.map(([f, g, m]) => `${f === "value" ? "değer" : "para birimi"} GA4'te ${q(g)}, Meta'da ${q(m)}`).join("; ")}. Etiketlerden biri yanlış veriyi okuyor.`,
     serverSide: (platform, server, browser) => `${platform}: ${server.map(q).join(", ")} sitenin kendi alan adındaki bir sunucu konteynerine gönderildi (sunucu tarafı etiketleme)${browser.length ? `; ${browser.map(q).join(", ")} doğrudan tarayıcıdan gitti` : ""}. Meta ve TikTok olaylarının sunucu tarafı kopyaları tarayıcıdan geçmez, bu yüzden burada görünmez.`,
     dedupIdMissing: (platform, name) => `${platform} ${q(name)} tarayıcıdan olay kimliği olmadan gönderildi; sitede sunucu tarafı bir kurulum görüldü. Sunucu da bu olayı gönderiyorsa ${platform} ikisini eşleştiremez ve iki kez sayar.`,
     consentDefaultMissing: () => "dataLayer'da Google Consent Mode varsayılan komutu (gtag('consent', 'default', ...)) bulunamadı.",

package/src/replay.js

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