@analitikisler/ai-tag-debugger 0.5.2 → 0.6.1

package/CHANGELOG.md

@@ -1,7 +1,27 @@
 # Changelog
 
+## 0.6.1 (2026-10-12)
+
+- GA4 events were reported as "sent 2 times" on sites with Google signals or ads features. gtag.js also sends a copy of those events to `www.google.com/g/collect` (or `doubleclick.net`), which GA4 doesn't count. Those copies are now still answered locally and listed under network requests, but no longer counted as hits. Requests to `analytics.google.com` still count: it is a primary GA4 endpoint.
+- GA4 requests answered locally showed as "failed" in the network list, because Chromium reports answered keepalive requests as aborted. They now show the 204 the page received.
+- Hits are read as each request is sent, rather than when it is answered. A request sent while the page navigates away is then still counted, even if it is cancelled before it can be answered. Requests the private-network guard stops are taken back out and shown as "blocked".
+
+## 0.6.0 (2026-10-10)
+
+- **Report v3.** The HTML report has four tabs: Overview, Findings, Journeys, and Scope and plan. They switch with the URL hash, so links work across tabs and every view can be shared. Still no scripts; printing shows everything.
+  - Journeys show one journey at a time: a step list on the left and the selected step (with its Events, dataLayer and Network tabs) on the right. A journey opens on its first step with a problem.
+  - Finding cards have a severity icon and color, the platform and how many journeys and steps they cover, an impact callout, numbered fix steps and "Where" chips that open the step.
+  - Findings can be filtered by severity. Warnings are yellow and risks orange.
+  - The Scope and plan tab has a plan coverage table (each planned event on each journey: sent, not sent, or not expected) and the providers table with request counts. It replaces the "Matching the plan" list.
+  - Type sizes are 14, 12 and 24 px.
+- **Logos.** The AI Tag Debugger logo is in the header, with "by Analitik İşler" on the right and the Analitik İşler logo and an open source credit line in the footer. Each has a dark version, and there is a favicon. They are embedded in the report, and the MCP report server's CSP now allows `img-src data:` for them. `--no-branding` leaves the Analitik İşler parts out.
+- The AI is asked to mark numbers with `**…**` and names with backticks. The report shows those as bold and code and escapes everything else.
+- The report's top line reads "AI tracking audit" ("Yapay zekâ ile izleme denetimi" in Turkish) instead of "Tracking QA report".
+
 ## 0.5.2 (2026-10-09)
 
+First release on npm as `@analitikisler/ai-tag-debugger`. The test script now also runs on Node 20.
+
 Fixes from the review of 0.5.1.
 
 - Meta's newer advanced matching fields (`udff[em]`, `udff[ph]`, …) are redacted like `ud[…]`.

package/README.md

@@ -1,3 +1,5 @@
+English | [Türkçe](README.tr.md)
+
 # AI Tag Debugger
 
 **An open-source AI agent that QA-tests your website's analytics and ad tracking.**
@@ -49,7 +51,7 @@ Platforms: GA4 (including server-side GTM endpoints), Google Ads conversions, Me
 
 By default an audit checks GA4, Google Ads, Meta and TikTok. Pick others with `--providers ga4,meta,x`, `"providers"` in the config, or `providers` on the MCP `start_audit` and `run_audit` tools. You can choose from `ga4`, `google_ads`, `meta`, `tiktok`, `x`, `linkedin`, `microsoft_ads`, `pinterest`, `snapchat`, `clarity`, `hotjar`, `doubleclick` and `adsense`. Events are parsed for GA4, Google Ads, Meta, TikTok and X; the others show their network requests.
 
-Requests to providers you didn't choose are still answered locally, so they never reach those accounts either. They are left out of the timeline, the CSV and the checks, and only counted: the report shows "Providers checked: … · Out of scope: Microsoft Clarity, DoubleClick (61 requests skipped)", and each step says how many it skipped. Without `--providers`, any provider your measurement plan names is added to the default list. Planned events for providers you did leave out are listed in one info finding instead of being reported as missing. Tag manager and consent platform requests are always shown.
+Requests to providers you didn't choose are still answered locally, so they never reach those accounts either. They are left out of the timeline, the CSV and the checks, and only counted: the report lists them with their request counts (for example "61 out-of-scope requests were skipped: Microsoft Clarity, DoubleClick"), and each step says how many it skipped. Without `--providers`, any provider your measurement plan names is added to the default list. Planned events for providers you did leave out are listed in one info finding instead of being reported as missing. Tag manager and consent platform requests are always shown.
 
 ## How it works
 
@@ -101,17 +103,25 @@ Adding a native provider means implementing two functions in [`src/providers.js`
 Requires Node 20+.
 
 ```bash
-git clone https://github.com/analitikisler/ai-tag-debugger.git
-cd ai-tag-debugger
-npm install
-npx playwright install chromium   # run again after upgrading, so the browser matches Playwright
-export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY, or GEMINI_API_KEY
+npm install -g @analitikisler/ai-tag-debugger
+npx -y playwright@1.56.1 install chromium   # the browser version this release uses
+export ANTHROPIC_API_KEY=...                # or OPENAI_API_KEY, or GEMINI_API_KEY
+
+ai-tag-debugger run --site https://staging.yourshop.com --journey add_to_cart --headed
 ```
 
-Try it on the included demo shop. It has three deliberate tracking bugs:
+Or run it without installing: `npx -y @analitikisler/ai-tag-debugger run --site … --journey add_to_cart`.
+
+### Try the demo shop (from source)
+
+The repository includes a demo shop with three deliberate tracking bugs:
 
 ```bash
-npm run demo:serve        # in one terminal: http://localhost:4321
+git clone https://github.com/analitikisler/ai-tag-debugger.git
+cd ai-tag-debugger
+npm install
+npx playwright install chromium   # run again after upgrading, so the browser matches Playwright
+npm run demo:serve                # in one terminal: http://localhost:4321
 node src/cli.js run --config examples/demo.config.json --out reports/demo
 open reports/demo/report.html
 ```
@@ -227,12 +237,16 @@ The exit code is `1` when findings reach `--fail-on` (default `broken`), so it c
 
 Output:
 
-- `report.html`: a summary with the most important problem first, findings grouped by severity (each with its impact, likely cause, evidence and fix steps), and a **full event timeline**. Every step of every journey has three tabs:
-  - **Events**: each tracking hit with its parameters, consent state, the dataLayer push and request behind it, and a note when a finding points at it.
-  - **dataLayer**: every push in the step.
-  - **Network requests**: every request to the chosen providers, decoded into a parameter table with a `?` tip on each parameter. A batched GA4 request shows each of its events.
+- `report.html`: one file with four tabs. Links work across tabs (a finding's "Where" chip opens that step), and every view has its own URL you can bookmark or share.
+  - **Overview**: problem counts, the AI summary (most important problem first, plus things worth checking that the findings don't cover), the journeys with their problem counts, and the providers checked.
+  - **Findings**: grouped by severity and filterable. Each one has its impact, likely cause, evidence, numbered fix steps and the steps where it happened.
+  - **Journeys**: one journey at a time, with its steps on the left and the selected step on the right. It opens on the first step with a problem. Each step has three tabs:
+    - **Events**: each tracking hit with its parameters, consent state, the dataLayer push and request behind it, and a note when a finding points at it.
+    - **dataLayer**: every push in the step.
+    - **Network requests**: every request to the chosen providers, decoded into a parameter table with a `?` tip on each parameter. A batched GA4 request shows each of its events.
+  - **Scope and plan**: whether each planned event was sent on each journey, and the providers checked or left out, with request counts.
 
-  Events and requests can be filtered by source. GA4 item strings (`pr1`…) and dataLayer `ecommerce.items` are shown as item cards, with custom item parameters in their own group. The report has no scripts.
+  Events and requests can be filtered by source. GA4 item strings (`pr1`…) and dataLayer `ecommerce.items` are shown as item cards, with custom item parameters in their own group. The report has no scripts: tabs and filters are plain HTML and CSS (they need Chrome 105, Safari 15.4 or Firefox 121 or newer), and printing shows every tab. The logos are embedded, so nothing is loaded from the internet. `--no-branding` leaves out the Analitik İşler logo and credit line.
 - `timeline.csv`: the same timeline as one row per hit, dataLayer push and network call, ready for Excel or Google Sheets.
 - `report.md`: the report in Markdown, e.g. for a pull request comment.
 - `capture.json`: everything captured, for your own analysis.
@@ -259,20 +273,22 @@ The browser runs on the computer where the server runs, so it can reach your sta
 
 ### Apps that start a local server: Claude Desktop, Gemini CLI, Cursor, VS Code, Claude Code
 
-Add the server to the app's MCP config, pointing at your copy of the repository. For Claude Desktop that is Settings → Developer → Edit Config (`claude_desktop_config.json`):
+Add the server to the app's MCP config. For Claude Desktop that is Settings → Developer → Edit Config (`claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "ai-tag-debugger": {
-      "command": "node",
-      "args": ["/path/to/ai-tag-debugger/src/cli.js", "mcp"]
+      "command": "npx",
+      "args": ["-y", "@analitikisler/ai-tag-debugger", "mcp"]
     }
   }
 }
 ```
 
-Gemini CLI uses the same `mcpServers` block in `~/.gemini/settings.json`. Claude Code: `claude mcp add ai-tag-debugger -- node /path/to/ai-tag-debugger/src/cli.js mcp`. Restart the app, and the ai-tag-debugger tools appear. If the app can't find `node`, use its full path (`which node`). Reports are written to `~/ai-tag-debugger-reports`.
+Install the browser once with `npx -y playwright@1.56.1 install chromium`. Gemini CLI uses the same `mcpServers` block in `~/.gemini/settings.json`. Claude Code: `claude mcp add ai-tag-debugger -- npx -y @analitikisler/ai-tag-debugger mcp`. Restart the app, and the ai-tag-debugger tools appear. If the app can't find `npx`, use its full path (`which npx`, for example `/opt/homebrew/bin/npx` on a Mac with Homebrew). Reports are written to `~/ai-tag-debugger-reports`.
+
+Running from a clone instead? Use `"command": "node"` and `"args": ["/path/to/ai-tag-debugger/src/cli.js", "mcp"]`.
 
 ### Apps that connect to a URL: ChatGPT, Gemini
 
@@ -280,7 +296,7 @@ These apps connect to MCP servers over HTTPS (in ChatGPT, through developer mode
 
 ```bash
 cloudflared tunnel --url http://localhost:8787     # or: ngrok http 8787; note the https address it prints
-node src/cli.js mcp --http --port 8787 --public-url https://<your-tunnel-address>
+npx -y @analitikisler/ai-tag-debugger mcp --http --port 8787 --public-url https://<your-tunnel-address>
 ```
 
 The server prints a URL with a random secret path, like `https://<your-tunnel-address>/mcp/<secret>`. Add that URL as a connector in the app. Anyone with the URL can use the browser on your machine, so keep it private and stop the server when you're done. A secret of your own (`--token`) must be at least 16 characters.

package/README.tr.md

@@ -0,0 +1,346 @@
+[English](README.md) | Türkçe
+
+# AI Tag Debugger
+
+**Sitenizdeki analitik ve reklam ölçümlemesini test eden açık kaynak bir yapay zekâ ajanı.**
+
+Bir yapay zekâ modeli, gerçek bir tarayıcıda önemli senaryolarınızı (ürün → sepet → ödeme, form doldurma) gerçek bir ziyaretçi gibi gezer. Gezinirken `ai-tag-debugger`, GA4, Google Ads, Meta Pixel ve TikTok'a giden her isteği ve her dataLayer push'unu kaydeder. Sonra bunları ölçümleme planınıza ve Consent Mode ayarlarınıza göre kontrol eder ve neyin bozulduğunu, nasıl düzeltileceğini anlaşılır bir dille, Türkçe ya da İngilizce bir raporda yazar.
+
+İki şekilde kullanabilirsiniz:
+
+- **Terminalden ya da CI'dan**, Anthropic (Claude), OpenAI, Google Gemini ya da OpenAI uyumlu herhangi bir API (Kimi, GLM, DeepSeek, OpenRouter, bilgisayarınızdaki Ollama ve daha fazlası) için kendi API anahtarınızla.
+- **Yapay zekâ asistanınızdan** (Claude, ChatGPT, Gemini ve MCP destekleyen diğer uygulamalar). Testi uygulamanın kendi modeli yürütür, yani ayrı bir API anahtarına gerek yoktur.
+
+[Analitik İşler](https://analitikisler.com/tr/) tarafından geliştirildi. MIT lisanslı.
+
+```
+▶ checkout (mobile)
+  Accept cookies
+  Open the first product
+  Add to cart
+  Open the cart
+  Go to checkout
+  …
+  Place the order
+  ✓ All scripted steps completed. · 20 tracking hits captured
+
+2 broken · 1 risk · 1 warning · 4 ok
+Report: reports/demo/report.html
+```
+
+## Neden
+
+Ölçümleme sessizce bozulur. Yeniden tasarımda bir butonun adı değişir, yeni bir şablon bir alanı unutur, çerez onayı banner'ındaki bir güncelleme pikselleri erken çalıştırır. Kimseye uyarı gelmez. Reklam platformları haftalarca hatalı dönüşümlerle optimizasyon yaptıktan sonra fark edersiniz.
+
+Tag'leri elle test etmek bunu yakalar, ama zahmetli olduğu için her sürümden sonra pek yapılmaz. `ai-tag-debugger` bunu CI'da çalıştırabileceğiniz tek bir komuta dönüştürür.
+
+## Neleri kontrol eder
+
+| Kontrol | Örnek bulgu |
+|---|---|
+| Eksik event'ler | `purchase`, ödeme senaryosunda hiç gönderilmedi |
+| Eksik parametreler | `purchase`, mobilde `value` ve `currency` olmadan gönderildi |
+| 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ış |
+| Kişisel veri | Bir e-posta adresi reklam platformuna açık metin olarak gönderildi |
+| Planda olmayan event'ler | Ölçümleme planınızda bulunmayan event'ler gönderiliyor |
+
+Platformlar: GA4 (server-side GTM adresleri dahil), Google Ads dönüşümleri, Meta Pixel, TikTok Pixel ve temel X Pixel event'leri.
+
+### Kontrol edilecek platformları seçin
+
+Varsayılan olarak bir test GA4, Google Ads, Meta ve TikTok'u kontrol eder. Başka platformları `--providers ga4,meta,x` ile, ayar dosyasındaki `"providers"` ile ya da MCP `start_audit` ve `run_audit` araçlarındaki `providers` ile seçebilirsiniz. Seçenekler: `ga4`, `google_ads`, `meta`, `tiktok`, `x`, `linkedin`, `microsoft_ads`, `pinterest`, `snapchat`, `clarity`, `hotjar`, `doubleclick` ve `adsense`. GA4, Google Ads, Meta, TikTok ve X için event'ler ayrıştırılır; diğerlerinin ağ istekleri gösterilir.
+
+Seçmediğiniz platformlara giden istekler de yerelde yanıtlanır, yani o hesaplara da ulaşmaz. Bu istekler zaman akışına, CSV'ye ve kontrollere alınmaz, sadece sayılır: rapor bunları istek sayılarıyla listeler (örneğin "Kapsam dışı 61 istek atlandı: Microsoft Clarity, DoubleClick") ve her adım kaç istek atladığını gösterir. `--providers` vermezseniz, ölçümleme planınızda geçen her platform varsayılan listeye eklenir. Dışarıda bıraktığınız platformlar için planlanmış event'ler eksik olarak raporlanmaz, tek bir bilgi bulgusunda listelenir. Tag yöneticisi ve çerez onayı platformu istekleri her zaman gösterilir.
+
+## Nasıl çalışır
+
+1. **Gezinme:** yapay zekâ modeline sade bir dille yazılmış bir hedef ("herhangi bir ürünü sepete ekle ve test ödeme yöntemiyle siparişi tamamla") ve sayfanın metin görünümü verilir. Model, Playwright üzerinden adım adım iki araç kullanır: `browser_action` (goto, click, fill, select, scroll, wait) ve `finish`.
+2. **Kayıt:** ölçümleme adreslerine giden her istek ayrıştırılıp standart bir biçime getirilir ve onu oluşturan adımla etiketlenir. Her dataLayer push'u, `gtag('consent', ...)` komutları dahil, bir init script ile kaydedilir. Varsayılan olarak GA4, Google Ads, Meta, TikTok, Microsoft Ads, LinkedIn, Pinterest, Snapchat ve X'in veri toplama istekleri yerelde yanıtlanır, yani **test trafiği bu gerçek hesaplara ulaşmaz**. Diğer sağlayıcıların tag'leri isteklerini göndermeye devam eder; zaman akışının ağ bölümü her çağrıyı ve yerelde yanıtlanıp yanıtlanmadığını gösterir.
+3. **Kontrol:** kurallar, yakalanan istekleri ölçümleme planınızla karşılaştırır. Bu kısım hiçbir API çağrısı yapmaz, bu yüzden sonuçlar tekrarlanabilirdir.
+4. **Açıklama:** model bulguları, her adımdaki istekleri ve (isterseniz) GTM container dışa aktarımınızı okur. Her sorunun olası nedenini ve çözümünü, ilgili tag ve trigger'ları adıyla anarak yazar.
+
+## Yapay zekâ sağlayıcıları
+
+Kendi API anahtarınızı kullanırsınız. `ai-tag-debugger` her sağlayıcının resmi SDK'sını kullanır:
+
+| Sağlayıcı | API anahtarı değişkeni | Varsayılan model |
+|---|---|---|
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` | `claude-opus-5-5` |
+| OpenAI | `OPENAI_API_KEY` | `gpt-5.5` |
+| Google Gemini | `GEMINI_API_KEY` | `gemini-pro-latest` |
+
+Sağlayıcı, hangi anahtar tanımlıysa ona göre seçilir (birden fazlası tanımlıysa önce Anthropic). Açıkça seçmek için `--provider anthropic|openai|gemini` ya da ayar dosyasında `"provider"` kullanın; başka bir model için `--model` verin. Gezinme, maliyeti düşük tutmak için düşük reasoning effort ister; açıklamalar ise yüksek effort ve yapılandırılmış JSON çıktısı ister.
+
+### OpenAI uyumlu her API: Kimi, GLM, DeepSeek, OpenRouter, Ollama ve daha fazlası
+
+Birçok sağlayıcı, OpenAI'ınkine benzer çalışan bir API sunar. `ai-tag-debugger`'ı adresini ve model kimliğini vererek bu API'lere yönlendirebilirsiniz:
+
+```bash
+export OPENAI_COMPATIBLE_API_KEY=...        # leave unset for a local Ollama
+ai-tag-debugger run --site https://yourshop.com --journey add_to_cart \
+  --provider openai-compatible --base-url <API address> --model <model id>
+```
+
+| Sağlayıcı | `--base-url` |
+|---|---|
+| Moonshot (Kimi) | `https://api.moonshot.ai/v1` |
+| Z.ai (GLM) | `https://api.z.ai/api/paas/v4` |
+| DeepSeek | `https://api.deepseek.com` |
+| Mistral | `https://api.mistral.ai/v1` |
+| Groq | `https://api.groq.com/openai/v1` |
+| OpenRouter (yüzlerce model) | `https://openrouter.ai/api/v1` |
+| Bilgisayarınızdaki Ollama | `http://localhost:11434/v1` |
+
+Model kimliğini sağlayıcınızın dokümantasyonundan alın. Bayrakların yerine `OPENAI_COMPATIBLE_BASE_URL` ve `OPENAI_COMPATIBLE_MODEL` değişkenlerini ya da ayar dosyasında `"provider"`, `"base_url"` ve `"model"` alanlarını da kullanabilirsiniz. API katı JSON şeması döndüremiyorsa, açıklamalar düz JSON moduna geçer.
+
+**Model seçimi hakkında.** Yapay zekâ, 5 ile 30 adım arasında, her adımda bir araç çağırarak gezinir. Modeller bunu ne kadar güvenilir yaptıkları konusunda çok farklıdır: küçük ve yerel modeller yanlış yere tıklayabilir, döngüye girebilir ya da erken durabilir. Kontroller modelin ne yaptığından bağımsız olarak doğru kalır, çünkü yakalanan isteklere dayanır. Ama tamamlanmayan bir senaryo, sonraki adımlardaki event'leri gösteremez. Bir model zorlanıyorsa daha büyük bir model, kısa hedefli hazır bir senaryo ya da `--max-steps` deneyin. Test edilmiş olanlar Anthropic, OpenAI ve Gemini varsayılanlarıdır.
+
+Yeni bir yerleşik sağlayıcı eklemek için [`src/providers.js`](src/providers.js) içinde iki fonksiyon yazmanız yeterli: araç çağıran bir konuşma ve yapılandırılmış bir JSON çağrısı.
+
+## Hızlı başlangıç
+
+Node 20 ve üstü gerekir.
+
+```bash
+npm install -g @analitikisler/ai-tag-debugger
+npx -y playwright@1.56.1 install chromium   # the browser version this release uses
+export ANTHROPIC_API_KEY=...                # or OPENAI_API_KEY, or GEMINI_API_KEY
+
+ai-tag-debugger run --site https://staging.yourshop.com --journey add_to_cart --headed
+```
+
+Ya da kurmadan çalıştırın: `npx -y @analitikisler/ai-tag-debugger run --site … --journey add_to_cart`.
+
+### Demo mağazayı deneyin (kaynak koddan)
+
+Depoda, bilerek bırakılmış üç ölçümleme hatası olan bir demo mağaza var:
+
+```bash
+git clone https://github.com/analitikisler/ai-tag-debugger.git
+cd ai-tag-debugger
+npm install
+npx playwright install chromium   # run again after upgrading, so the browser matches Playwright
+npm run demo:serve                # in one terminal: http://localhost:4321
+node src/cli.js run --config examples/demo.config.json --out reports/demo
+open reports/demo/report.html
+```
+
+Henüz API anahtarınız yok mu? Kayıtlı adımları hiçbir yapay zekâ modeli kullanmadan tekrar oynatın:
+
+```bash
+node src/cli.js run --config examples/demo.config.json --scripted --no-ai --out reports/demo
+```
+
+## Neyi test edeceğinizi seçin
+
+Başlamak için ayar dosyasına gerek yok. Hazır senaryoları seçin, kendi senaryonuzu kendi cümlenizle yazın ve kontrolü önem verdiğiniz event'lerle sınırlayın:
+
+```bash
+# Ready-made journeys come with a goal and the GA4 and Meta events to expect.
+ai-tag-debugger run --site https://staging.yourshop.com --journey purchase --journey sign_up
+
+# Describe a journey in your own words. The events you name are expected on it.
+ai-tag-debugger run --site https://yoursite.com --goal "Subscribe to the newsletter in the footer" --events newsletter_signup
+
+# Only check some events.
+ai-tag-debugger run --config ai-tag-debugger.config.json --events purchase,add_to_cart
+```
+
+Hedefi Türkçe de yazabilirsiniz, örneğin `--goal "Sayfanın altındaki bültene abone ol"`.
+
+| Hazır senaryo | Yapay zekânın yaptığı | Beklenen event'ler |
+|---|---|---|
+| `purchase` (ya da `checkout`) | Ürün → sepet → ödeme → test ödeme seçeneğiyle sipariş | GA4 `view_item`, `add_to_cart`, `begin_checkout`, `purchase`; Meta `AddToCart`, `InitiateCheckout`, `Purchase` |
+| `add_to_cart` (ya da `cart`) | Bir ürün açar ve sepete ekler | GA4 `view_item`, `add_to_cart`; Meta `AddToCart` |
+| `sign_up` (ya da `signup`, `register`) | Test verileriyle hesap oluşturur | GA4 `sign_up`; Meta `CompleteRegistration` |
+| `lead` (ya da `contact`, `form`) | İletişim, teklif ya da demo formunu doldurup gönderir | GA4 `generate_lead`; Meta `Lead` |
+| `search` | Sitede arama yapar ve bir sonucu açar | `search_term` ile GA4 `search`; Meta `Search` |
+
+`--journey`, ayar dosyanızdaki senaryoları da id'leriyle seçer. Ayar dosyasıyla birlikte kullanıldığında hazır senaryolar kendi event'lerini planınıza ekler.
+
+### API kullanımını düşük tutmak
+
+Her gezinme adımı bir model çağrısıdır. Yani kullanım **senaryo × ekran boyutu × adım** ile artar, buna sonda bulguları açıklayan bir çağrı eklenir. Kontroller hiçbir zaman modeli çağırmaz.
+
+- **Sadece ihtiyacınız olan senaryoları çalıştırın.** En büyük tasarruf budur: tam `purchase` senaryosu yerine `--journey add_to_cart`, on ya da daha fazla adım yerine birkaç adım sürer.
+- **Tek ekran boyutu kullanın.** `--viewport mobile`, masaüstü ve mobile göre çağrıları yarıya indirir.
+- **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.
+- **Bir yapay zekâ asistanı kullanın.** MCP üzerinden gezinmeyi asistanın kendi modeli yapar, hiç API anahtarı kullanılmaz.
+
+## Sitenizi ayarlayın
+
+`ai-tag-debugger.config.json`:
+
+```json
+{
+  "site": "https://staging.yourshop.com",
+  "plan": "measurement-plan.json",
+  "gtm_container": "GTM-XXXX_workspace.json",
+  "viewports": ["desktop", "mobile"],
+  "journeys": [
+    {
+      "id": "checkout",
+      "goal": "Accept cookies, add any product to the cart and complete checkout using the test payment method."
+    }
+  ]
+}
+```
+
+| Alan | Anlamı |
+|---|---|
+| `site` | Ana adres. Mümkünse staging kullanın. |
+| `plan` | Ölçümleme planı: bir dosya yolu ya da satır içi bir nesne (aşağıda). Hazır senaryolarla isteğe bağlıdır. |
+| `gtm_container` | İsteğe bağlı GTM container dışa aktarımı (Admin → Export container). Böylece açıklamalarda tag ve trigger'lar adıyla geçer. |
+| `viewports` | `desktop` ve/veya `mobile`. |
+| `journeys` | `--journey` ile hazır senaryo seçtiğinizde ya da `--goal` ile kendi senaryonuzu yazdığınızda isteğe bağlıdır. |
+| `journeys[].goal` | Yapay zekânın yapması gereken, sade bir dille. |
+| `journeys[].start` | İsteğe bağlı başlangıç yolu (varsayılan `/`). |
+| `journeys[].steps` | `--scripted` çalıştırmaları için isteğe bağlı sabit adımlar: `{ "action": "click", "selector": "#add-to-cart" }`. |
+| `allowed_hosts` | Senaryoların gidebileceği diğer adresler, örneğin harici bir ödeme sayfası için `["checkout.payments-provider.com"]`. Bunun dışında tarayıcı `site` adresinde ve alt alan adlarında kalır. `--allow-host` ile aynıdır. |
+| `providers` | Kontrol edilecek ölçümleme platformları, örneğin `["ga4", "meta"]`. Varsayılan `["ga4", "google_ads", "meta", "tiktok"]`. `--providers` ile aynıdır. |
+| `block_hits` | Varsayılan `true`. İsteklerin gerçek adreslerinize ulaşmasına izin vermek için `false` yapın. |
+| `language` | Rapor dili, `en` (varsayılan) ya da `tr`. `--lang` ile aynıdır. |
+| `keep_bodies` | Varsayılan `false`. Ölçümleme isteklerini kullanıcı verilerini gizlemeden, gönderildiği haliyle saklamak için `true` yapın. `--keep-bodies` ile aynıdır. |
+| `branding` | Varsayılan `true`. Analitik İşler logosunu ve "AI Tag Debugger ile oluşturuldu · analitikisler.com" satırını raporlardan çıkarmak için `false` yapın. `--no-branding` ya da MCP `finish_audit` ve `run_audit` araçlarında `branding: false` ile aynıdır. |
+| `provider` | İsteğe bağlı: `anthropic`, `openai`, `gemini` ya da `openai-compatible`. `--provider` ile aynıdır. |
+| `base_url`, `model` | İsteğe bağlı: API adresi ve model kimliği, örneğin `openai-compatible` için. `--base-url` ve `--model` ile aynıdır. |
+
+`measurement-plan.json`:
+
+```json
+{
+  "consent_mode": true,
+  "events": [
+    { "platform": "ga4", "name": "add_to_cart", "required_params": ["currency", "value", "items"] },
+    { "platform": "ga4", "name": "purchase", "journeys": ["checkout"], "required_params": ["transaction_id", "currency", "value", "items"] },
+    { "platform": "meta", "name": "Purchase", "journeys": ["checkout"], "required_params": ["value", "currency"] }
+  ]
+}
+```
+
+`platform` değeri `ga4`, `google_ads`, `meta` ya da `tiktok` olabilir. `journeys`, bir event'in hangi senaryolarda beklendiğini sınırlar (varsayılan: her senaryo). Tek bir işlemde birden fazla kez gönderilmesi normal olan event'ler için `allow_multiple: true` kullanın.
+
+## CLI
+
+```
+ai-tag-debugger run [--site <url>] [--config <file>] [--journey <id>] [--goal "<text>"] [--events <names>]
+                [--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]
+ai-tag-debugger mcp [--http] [--port <n>] [--host <addr>] [--token <secret>] [--public-url <https url>] [--reports <dir>]
+                [--allow-private-network]
+```
+
+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:
+
+- `report.html`: dört sekmeli tek bir dosya. Sekmeler arası bağlantılar çalışır (bir bulgudaki "Nerede" etiketi o adımı açar) ve her görünümün kaydedip paylaşabileceğiniz kendi adresi vardır.
+  - **Genel bakış**: sorun sayıları, yapay zekâ özeti (en önemli sorun en üstte, ayrıca bulguların kapsamadığı ama kontrol etmeye değer noktalar), sorun sayılarıyla senaryolar ve kontrol edilen platformlar.
+  - **Bulgular**: önem derecesine göre gruplanır ve filtrelenebilir. Her bulgunun etkisi, olası nedeni, kanıtı, numaralı çözüm adımları ve oluştuğu adımlar vardır.
+  - **Yolculuklar**: her seferinde bir senaryo; solda adımları, sağda seçili adım. İlk sorunlu adımda açılır. Her adımın üç sekmesi vardır:
+    - **Olaylar**: parametreleri, çerez onayı durumu, arkasındaki dataLayer push'u ve isteğiyle birlikte her ölçümleme isteği; bir bulgu ona işaret ediyorsa bir not.
+    - **dataLayer**: adımdaki her push.
+    - **Ağ istekleri**: seçilen platformlara giden her istek; her parametrede `?` ipucu olan bir parametre tablosuna çözülmüş halde. Toplu gönderilen bir GA4 isteği, içindeki her event'i gösterir.
+  - **Kapsam ve plan**: planlanan her event'in her senaryoda gönderilip gönderilmediği ve istek sayılarıyla kontrol edilen ya da dışarıda bırakılan platformlar.
+
+  Event'ler ve istekler kaynağa göre filtrelenebilir. GA4 ürün dizeleri (`pr1`…) ve dataLayer `ecommerce.items` ürün kartları olarak, özel ürün parametreleri ayrı bir grupta gösterilir. Raporda script yoktur: sekmeler ve filtreler düz HTML ve CSS'tir (Chrome 105, Safari 15.4 ya da Firefox 121 ve üstü gerekir) ve yazdırınca tüm sekmeler görünür. Logolar dosyanın içindedir, internetten hiçbir şey yüklenmez. `--no-branding` Analitik İşler logosunu ve imza satırını çıkarır.
+- `timeline.csv`: aynı zaman akışı; her istek, dataLayer push'u ve ağ çağrısı bir satır, Excel ya da Google Sheets için hazır.
+- `report.md`: raporun Markdown hali, örneğin bir pull request yorumu için.
+- `capture.json`: yakalanan tüm veriler, kendi analiziniz için.
+
+Raporlar bir imza satırıyla biter: "AI Tag Debugger ile oluşturuldu · analitikisler.com". Buradaki alan adı düz bir bağlantıdır (resim yok, takip yok, referrer gönderilmez, böylece rapor adresleri sızmaz). `--no-branding` bu satırı logoyla birlikte kaldırır.
+
+Türkçe rapor için `--lang tr` kullanın. Bulgu metinleri, başlıklar, modelin açıklamaları ve çözümleri Türkçe yazılır; ajan da adımlarını Türkçe anlatır.
+
+## Yapay zekâ asistanınızdan kullanın (MCP)
+
+`ai-tag-debugger mcp`, bir [Model Context Protocol](https://modelcontextprotocol.io) sunucusu başlatır. Böylece testi asistanınızın modeli kendisi yürütür: "staging.magazam.com'da ödeme adımlarının ölçümlemesini kontrol et" dersiniz, tarayıcıyı açar, adımları tıklar ve bulguları sohbette açıklar. API anahtarı gerekmez, çünkü düşünme işini uygulamanın kendi modeli yapar.
+
+Sunucunun sunduğu araçlar:
+
+| Araç | Ne yapar |
+|---|---|
+| `start_audit` | Bir adreste yeni bir tarayıcı açar ve tüm ölçümleme isteklerini kaydetmeye başlar. Hedefini ve beklenen event'lerini almak için hazır bir senaryo (`purchase`, `sign_up`, …), neyin kontrol edileceğini seçmek için `providers` verin. Asistan önce size hangi platformların kontrol edileceğini sorar. |
+| `browser_action` | Tek bir click, fill, select, goto, scroll ya da wait. Sayfayı ve o adımda gönderilen ölçümleme isteklerini döndürür. |
+| `get_page` | Mevcut sayfayı gösterir. |
+| `finish_audit` | Her şeyi ölçümleme planınıza (JSON) ya da hazır senaryonun event'lerine göre, isterseniz sadece adını verdiğiniz `events` için kontrol eder ve zaman akışıyla birlikte tam HTML raporu yazar. |
+| `run_audit` | Bir ayar dosyasını baştan sona çalıştırır (sadece yerelde). |
+
+Tarayıcı, sunucunun çalıştığı bilgisayarda çalışır. Bu yüzden staging ve `localhost` sitelerinize erişebilir. Ölçümleme istekleri her zamanki gibi yerelde yanıtlanır.
+
+### Yerel sunucu başlatan uygulamalar: Claude Desktop, Gemini CLI, Cursor, VS Code, Claude Code
+
+Sunucuyu uygulamanın MCP ayarlarına ekleyin. Claude Desktop'ta bu Settings → Developer → Edit Config'tir (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ai-tag-debugger": {
+      "command": "npx",
+      "args": ["-y", "@analitikisler/ai-tag-debugger", "mcp"]
+    }
+  }
+}
+```
+
+Tarayıcıyı bir kez `npx -y playwright@1.56.1 install chromium` ile kurun. Gemini CLI, `~/.gemini/settings.json` içinde aynı `mcpServers` bloğunu kullanır. Claude Code için: `claude mcp add ai-tag-debugger -- npx -y @analitikisler/ai-tag-debugger mcp`. Uygulamayı yeniden başlatın, ai-tag-debugger araçları görünür. Uygulama `npx`'i bulamazsa tam yolunu kullanın (`which npx`; örneğin Homebrew kurulu bir Mac'te `/opt/homebrew/bin/npx`). Raporlar `~/ai-tag-debugger-reports` klasörüne yazılır.
+
+Kaynak koddan mı çalıştırıyorsunuz? `"command": "node"` ve `"args": ["/path/to/ai-tag-debugger/src/cli.js", "mcp"]` kullanın.
+
+### Bir adrese bağlanan uygulamalar: ChatGPT, Gemini
+
+Bu uygulamalar MCP sunucularına HTTPS üzerinden bağlanır (ChatGPT'de, planınıza bağlı olarak developer mode connector'ları ile). Sunucuyu HTTP modunda başlatın ve bir tünelle internete açın:
+
+```bash
+cloudflared tunnel --url http://localhost:8787     # or: ngrok http 8787; note the https address it prints
+npx -y @analitikisler/ai-tag-debugger mcp --http --port 8787 --public-url https://<your-tunnel-address>
+```
+
+Sunucu, rastgele gizli bir yol içeren bir adres yazdırır, örneğin `https://<your-tunnel-address>/mcp/<secret>`. Bu adresi uygulamaya connector olarak ekleyin. Adrese sahip olan herkes bilgisayarınızdaki tarayıcıyı kullanabilir; adresi kimseyle paylaşmayın ve işiniz bitince sunucuyu kapatın. Kendi belirlediğiniz bir gizli anahtar (`--token`) en az 16 karakter olmalıdır.
+
+HTTP modunda sunucu, yereldekinden daha kısıtlıdır:
+
+- Diskinizden ölçümleme planı ya da ayar dosyası okumaz (planı sohbette JSON metni olarak verin) ve `run_audit` sunulmaz. Sadece kendi yazdığı raporları sunar.
+- Tarayıcı sadece `http` ve `https` sayfalarını açar; `localhost` ve özel ağ adreslerini (`192.168.x.x` ya da `169.254.169.254` gibi) reddeder, böylece adres ağınızın içini görmek için kullanılamaz. WebSocket'ler dahil tüm tarayıcı trafiği küçük bir yerleşik proxy'den geçer. Bu proxy her adresi bir kez çözümler ve sadece kontrol ettiği IP'ye bağlanır, böylece test sırasında değişen bir DNS yanıtı bu kontrolü aşamaz. Yerel bir staging sitesini yine de bu şekilde test etmek için sunucuyu `--allow-private-network` ile başlatın.
+- 15 dakika açık kalan testler kapatılır ve istek gövdeleri 1 MB ile sınırlıdır.
+
+Tünele gerek kalmayan, hazır bir adresle barındırılan sunucu, [Analitik İşler](https://analitikisler.com/tr/) Cloud sürümünün bir parçasıdır.
+
+## Güvenlik
+
+- Ajana bariz test verileri kullanması ve **asla gerçek ödeme bilgisi girmemesi** söylenir. Bir senaryo gerçek bir ödeme ya da hesap gerektiriyorsa, durur ve bunu raporlar.
+- [Nasıl çalışır](#nasıl-çalışır) bölümünde listelenen platformlara giden ölçümleme istekleri varsayılan olarak yerelde yanıtlanır, böylece bu analitik ve reklam hesaplarına test dönüşümleri gitmez.
+- Tarayıcı test edilen sitede ve alt alan adlarında, ayrıca `allowed_hosts` içindeki adreslerde kalır. Sadece `http` ve `https` sayfalarını açar.
+- Modele, sayfa içeriğinin talimat değil veri olduğu söylenir. Bir prompt kuralı, modelin hiçbir zaman yanıltılmayacağını garanti edemez; bu yüzden yukarıdaki gezinme sınırları, yanıltılmış bir modelin yapabileceklerini kısıtlar.
+- Tarayıcı, ortamında API anahtarlarınız ve diğer gizli bilgiler olmadan çalışır.
+- **Reklam eşleştirmesi için gönderilen kullanıcı verileri**, `capture.json` dosyasına kaydedilmeden ya da raporda gösterilmeden önce **gizlenir**: GA4 ve Google Ads enhanced conversions (`em`, `ph`, `uid`, …), Meta advanced matching (`ud[*]`, `udff[*]`), TikTok `context.user` içindeki e-postalar, telefon numaraları, adlar, adresler ve kullanıcı kimlikleri ile sitenin enhanced conversions için dataLayer'a gönderdiği `user_data`. E-posta adresine benzeyen her değer, alanın adı ne olursa olsun gizlenir. Her değer `[redacted: 64 chars, looks hashed]` gibi bir işarete dönüşür; hash'lenmemiş bir değer kişisel veri riski olarak raporlanır. `--keep-bodies` (`"keep_bodies": true`) hata ayıklama için istekleri gönderildiği haliyle saklar.
+- Saklanan istek gövdeleri istek başına 32 KB ve senaryo başına 2 MB ile sınırlıdır. Bu sınırın üstünde rapor, gövdenin saklanmadığını belirtir.
+- Sadece size ait ya da test etme yetkiniz olan sitelerde çalıştırın.
+- HTTP sunucusunu başkaları için mi barındırıyorsunuz? Ek bir güvenlik katmanı olarak özel ağ ve bulut metadata adres aralıklarını ağ seviyesinde de engelleyin (bir egress firewall ya da izole bir ağ ile).
+
+## Yol haritası
+
+- Consent Check: çerez onayı banner'larının ve Consent Mode v2'nin GDPR/KVKK'ya göre daha derin denetimi.
+- Ölçümleme planı: bir adresten plan ve dataLayer şartnamesi taslağı hazırlama.
+- [analitikisler.com](https://analitikisler.com/tr/) üzerinde zamanlanmış testler, deploy webhook'ları, barındırılan MCP sunucusu ve ajanslar için çoklu site panelleri sunan barındırılan sürüm.
+
+## Geliştirme
+
+```bash
+npm test   # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
+```
+
+Uçtan uca testler sahte model istemcileri kullanır, bu yüzden API anahtarı olmadan çalışır.
+
+## Barındırılan sürüm
+
+Barındırılan testler, zamanlama ve ajans panelleri için [analitikisler.com](https://analitikisler.com/tr/) adresine bakın.
+
+## Lisans
+
+MIT © Analitik İşler

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "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": {

package/src/audit.js

@@ -37,7 +37,7 @@ export async function writeReports({ outDir, config, plan, runs, findings, expla
   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, lang, branding };
+  const report = { title, generatedAt, findings, explained, runs, plan, lang, branding };
   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));