@analitikisler/ai-tag-debugger 0.0.0-stage → 0.5.2

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+## 0.5.2 (2026-10-09)
+
+Fixes from the review of 0.5.1.
+
+- Meta's newer advanced matching fields (`udff[em]`, `udff[ph]`, …) are redacted like `ud[…]`.
+- dataLayer pushes are redacted too: email and phone fields, everything under `user_data` (including `gtag("set", "user_data", …)`), and email-like values. Page data with similar names, such as `page.city`, is kept. Unhashed user data in the dataLayer is reported as a warning: it is a valid setup for Google enhanced conversions, but every other tag on the page can read it. `--keep-bodies` keeps pushes as they were.
+- Any value that looks like an email address is redacted, whatever its field is called (for example `ep.customer_email`).
+- In bodies cut at the 32 KB limit, a value left open at the end is dropped, and numbers (such as a phone number sent as a number) are redacted by field name.
+
+## 0.5.1 (2026-10-09)
+
+Fixes from the review of 0.5.0.
+
+- **User data for ad matching is redacted** before requests are stored or shown: emails, phone numbers, names, addresses and user ids in GA4 and Google Ads enhanced conversions, Meta advanced matching (`ud[*]`) and TikTok `context.user`, in URLs, POST bodies and hit parameters. Each value becomes `[redacted: N chars, looks hashed]` or `[redacted: N chars, plain]`, and plain values are reported as a personal data risk. `--keep-bodies` or `"keep_bodies": true` stores requests as sent.
+- Stored request bodies are capped at 2 MB per journey on top of 32 KB per request. Requests past the limit say so in the report.
+- Without `--providers`, the providers named in the measurement plan are added to the defaults. Plan platforms are compared in lower case, so `"GA4"` matches. Planned events for providers that were left out are listed in an info finding instead of disappearing.
+- `report.md` escapes the report title and journey ids like the other fields.
+
+## 0.5.0 (2026-10-09)
+
+- **Report v2.** Every step has three tabs: Events, dataLayer and Network requests. They replace the per-event tabs and the "Other dataLayer pushes and network calls" box. Events and requests can be filtered by source (GA4, Google Ads, Meta, TikTok, …), with only the sources in the step offered. Still no scripts.
+- Each event shows its parameters, consent, a Source box (the matched dataLayer push and the request with host, method and status) and, when a finding points at it, a note saying what is wrong.
+- GA4 item strings (`pr1`…, including `k0`/`v0` custom item parameters) and dataLayer `ecommerce.items` are shown as item cards.
+- Network requests are decoded into parameter tables with a `?` tip on each parameter (a GA4, Google Ads, Meta, TikTok and X glossary in English and Turkish). Event parameters come first; session, device, page and consent parameters are collapsed. The raw request is kept under "Raw request".
+- GA4 batched POST bodies and TikTok JSON bodies are now recorded (up to 32 KB per request), so the Network tab shows every event in a batch.
+- The AI summary is structured: a headline, a ranked list of issues with severity tags, and "Not in the findings list, but worth checking". Each explanation has an impact line and numbered fix steps. Findings are grouped by severity and are collapsible, and evidence is shown as a table. Older captures with a plain-text summary still render.
+- **Choose the providers to check** with `--providers`, `"providers"` in the config, or `providers` on the MCP `start_audit` and `run_audit` tools (default GA4, Google Ads, Meta, TikTok). Requests to the others are still answered locally but are left out of the timeline, the CSV and the checks, and only counted. The report shows which providers were checked and how many requests were skipped, overall and per step. The MCP server asks the assistant to check with the user before starting.
+- Basic X (Twitter) Pixel parsing: event name, pixel id, value and quantity.
+
+## 0.4.9 (2026-10-09)
+
+- The project moved to the `analitikisler` GitHub organization: the npm package is now `@analitikisler/ai-tag-debugger`, the repository is github.com/analitikisler/ai-tag-debugger, and `package.json` lists the repository, homepage, issue tracker and author.
+
+## 0.4.8 (2026-10-09)
+
+- Reports (HTML and Markdown, English and Turkish) end with a credit line, "Generated by AI Tag Debugger · analitikisler.com". The domain is a link with `rel="noopener noreferrer"`, and there are no images or tracking. `--no-branding`, `"branding": false` in the config, or `branding: false` on the MCP `finish_audit` and `run_audit` tools removes it together with the Analitik İşler logo.
+- The README ends with a short pointer to the hosted version at analitikisler.com.
+
+## 0.4.7 (2026-10-09)
+
+- **Redesigned HTML report** in the Analitik İşler design system. Findings are cards linked to their step, there is a journey overview, and events are grouped by platform (GA4, Meta, Google Ads, TikTok, others). Each event has tabs for its parameters, its dataLayer push and its network calls. The report has no scripts, so it works under the report server's CSP and on phones down to 320px wide.
+- dataLayer pushes are linked to events by name, including gtag.js array pushes and pixel aliases (Meta `AddToCart` to `add_to_cart`, `Contact`, `SubmitForm`, `Subscribe`, `StartTrial` and more). Duplicate hits are paired with their pushes in order, and finding links pick the right step when step labels repeat.
+
+## 0.4.6 (2026-10-09)
+
+- Fix: elements whose class merely contains "cmp" (such as Adobe AEM's `cmp-navigation` headers) no longer count as consent banners. Real consent tools are still recognized by name.
+
+## 0.4.5 (2026-10-09)
+
+- Cookie and consent banners (OneTrust, Cookiebot, Usercentrics, Didomi, CookieYes and fixed elements named cookie, consent, GDPR or KVKK) block clicks underneath even when they cover less than half the screen.
+- Errors and notes that quote a covering element's text get the same untrusted-content treatment as the page view.
+- Ad slots in `about:blank` iframes (`google_ads_iframe_*`, `aswift_*`) are skipped.
+
+## 0.4.4 (2026-10-09)
+
+Fixes from the review of 0.4.3's element finding and clicking.
+
+- **No clicking through consent walls.** When something covers the element, the click is refused if the cover is a dialog, a modal, or covers at least half the screen, and the agent is told to deal with it first. Otherwise (a sticky header, a small badge), the agent clicks a part of the element nothing covers, with real mouse events. A synthetic click is only the last resort. Either way, the agent is told, and the report marks the step.
+- **Exact text matches first.** Clicking by `text` tries exact matches before partial ones, only visible elements, in the order button, link, label, placeholder, then any text, on the main page before iframes. When several elements match, the agent is asked to use a ref instead of a guess being made.
+- **Text reaches iframes.** Clicking by text also searches visible iframes.
+- **Fewer, better iframes.** Hidden, tiny and ad, analytics or consent vendor iframes are skipped, so they don't use up the list or get clicked. "Not in view" for iframe elements accounts for the frame's position on the page.
+- **Shadow DOM refs.** Old refs are cleared inside shadow roots too, so a stale element can't share a ref with a new one.
+- Faster page views on big pages (the pointer-cursor scan only looks near the visible area). Fewer duplicates: `label[for]` is no longer listed separately, and the shadow-root parent check is fixed. "More elements not listed" only shows when visible elements were actually left out. A non-integer `ref` is rejected.
+
+## 0.4.3 (2026-10-09)
+
+The agent finds the buttons real sites build.
+
+- **Custom controls are listed.** Besides links, buttons and form fields, the page view now includes controls built from divs and spans: role attributes, `tabindex`, and elements with a pointer cursor (such as a styled "Rezervasyon Yap" div with a JavaScript click handler). Labels also come from `aria-labelledby`, `<label for>`, image alt text and icon titles.
+- **On-screen elements come first.** Elements that are actually visible at their position are listed before those out of view, and covered or clipped ones (collapsed mega menus, overlays) come last. A long menu can no longer push the button the agent needs out of the list. Up to 250 elements are listed, up from 150.
+- **Iframes and shadow DOM.** Elements inside embedded frames (booking and payment widgets) and open shadow roots get refs too.
+- **Click by visible text.** `browser_action` accepts `text` instead of `ref`, e.g. `text: "Rezervasyon Yap"`, matching a button or link name, a label, a placeholder, or any visible text.
+- **More reliable clicks and scrolling.** A click blocked by a sticky header or overlay falls back to a direct click event. `scroll` takes `up` or `down`, and scrolls the window directly when the page ignores the mouse wheel.
+
+## 0.4.2 (2026-10-09)
+
+Follow-up hardening from the 0.4.1 re-review, for the HTTP MCP server.
+
+- **DNS rebinding.** When private addresses are blocked (`mcp --http`), all browser traffic goes through a small local proxy (`src/egress.js`). It resolves each host once, refuses private addresses, and connects to exactly the address it checked, so Chromium never resolves hosts itself.
+- **WebSockets.** `ws://` and `wss://` connections go through the same proxy, so the private-address block applies to them too. Non-proxied WebRTC UDP is turned off in this mode.
+- **IPv6 forms of private IPv4 addresses** (NAT64 `64:ff9b::/96`, 6to4 `2002::/16`, IPv4-compatible `::a.b.c.d`, hex-form IPv4-mapped) count as private, and Teredo addresses are refused.
+- README: the prompt-injection line no longer promises more than a prompt rule can, and hosted setups are advised to block private ranges at the network level as well.
+
+## 0.4.1 (2026-10-09)
+
+Security and robustness fixes from the first full code and security review, before the first public release.
+
+- **Navigation limits.** The audit browser now opens only `http` and `https` pages and stays on the audited site and its subdomains. Other hosts can be allowed with `allowed_hosts` in the config, `--allow-host`, or `allowed_hosts` on the MCP `start_audit` tool. Redirects and links that leave the site are blocked and the browser goes back.
+- **Private addresses blocked over HTTP.** In `mcp --http` mode, audits refuse `localhost`, private, link-local and similar addresses, for the start page, navigations and every request. `--allow-private-network` turns this off.
+- **Page content is untrusted.** The page view the model sees is wrapped in `<page_content>` tags, and the prompts say that this content is data, never instructions.
+- **No secrets in the browser.** Chromium starts without API keys, tokens and other secrets in its environment.
+- **MCP HTTP hardening.** Request bodies are limited to 1 MB, `--token` needs at least 16 characters, the secret is compared in constant time, binding to a non-loopback host prints a warning, and reports are served with security headers.
+- **Abandoned audits close.** MCP audits idle for 15 minutes are closed, and per-audit logs are capped.
+- **More beacons answered locally.** Google Ads remarketing (`viewthroughconversion`, `1p-user-list`, `ccm/collect`, `td.doubleclick.net`), Meta privacy sandbox, Microsoft Ads, LinkedIn, Pinterest, Snapchat and X pixels no longer reach real accounts during audits.
+- **Fixes.** A malformed `%` in a tracking URL no longer crashes the checks. An unknown viewport no longer leaks a browser. The Gemini key is read from the injected environment.
+- **Report safety.** CSV cells that start with `=`, `+`, `-` or `@` are prefixed so spreadsheets don't run them as formulas, and `report.md` escapes HTML in page-controlled values.
+- **Reproducible installs.** `package-lock.json` is committed and Playwright is pinned to 1.56.1. The CI example pins a released npm version, installs the matching browser, sets `permissions: contents: read` and passes one API key. The repository has its own test workflow.
+- The demo shop server listens on `127.0.0.1` only and checks paths correctly.
+
+## 0.4.0
+
+First complete version: CLI and MCP server, Anthropic, OpenAI, Gemini and OpenAI-compatible providers, ready-made journeys, Turkish reports, full event timeline and CSV.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Analitik İşler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,328 @@
-# Temporary Holding Version
+# AI Tag Debugger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**An open-source AI agent that QA-tests your website's analytics and ad tracking.**
+
+An AI model drives a real browser through your key journeys (product → cart → checkout, lead forms) like a real visitor. While it browses, `ai-tag-debugger` records every GA4, Google Ads, Meta Pixel and TikTok hit and every dataLayer push. It then checks them against your measurement plan and Consent Mode setup and writes a plain-language report of what broke and how to fix it, in English or Turkish.
+
+Use it in two ways:
+
+- **From your terminal or CI**, with your own API key for Anthropic (Claude), OpenAI, Google Gemini, or any OpenAI-compatible API (Kimi, GLM, DeepSeek, OpenRouter, a local Ollama and more).
+- **From your AI chat app** (Claude, ChatGPT, Gemini and other apps that support MCP). The app's own model drives the audit, so you don't need a separate API key.
+
+Built by [Analitik İşler](https://analitikisler.com). MIT licensed.
+
+```
+▶ 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
+```
+
+## Why
+
+Tracking breaks silently. A redesign renames a button, a new template forgets a field, a consent banner update lets pixels fire too early. Nobody gets an alert. You find out weeks later, after ad platforms have optimized on bad conversions.
+
+Manual tag QA catches this, but it's tedious, so it rarely happens after every release. `ai-tag-debugger` makes it a command you can run in CI.
+
+## What it checks
+
+| Check | Example finding |
+|---|---|
+| Missing events | `purchase` never fired on the checkout journey |
+| Missing parameters | `purchase` sent without `value` and `currency` on mobile |
+| 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 |
+| Personal data | An email address sent to an ad platform in plain text |
+| Unplanned events | Events firing that aren't in your measurement plan |
+
+Platforms: GA4 (including server-side GTM endpoints), Google Ads conversions, Meta Pixel, TikTok Pixel, and basic X Pixel events.
+
+### Choose the providers to check
+
+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.
+
+## How it works
+
+1. **Browse:** the AI model gets a goal in plain language ("add any product to the cart and complete checkout with the test payment") and a text view of the page. It acts through two tools, `browser_action` (goto, click, fill, select, scroll, wait) and `finish`, one step at a time with Playwright.
+2. **Capture:** every request to a tracking endpoint is parsed into normalized hits and tagged with the step that caused it. Every dataLayer push is recorded through an init script, including `gtag('consent', ...)` commands. By default, the collection requests of GA4, Google Ads, Meta, TikTok, Microsoft Ads, LinkedIn, Pinterest, Snapchat and X are answered locally, so **test traffic doesn't reach those real accounts**. Tags from other vendors still send their requests; the network part of the timeline shows each call and whether it was answered locally.
+3. **Check:** deterministic rules compare the hits with your measurement plan. This part needs no API calls, so results are reproducible.
+4. **Explain:** the model reads the findings, the hits per step and (optionally) your GTM container export. It writes the likely cause and fix for each problem, naming the tags and triggers involved.
+
+## AI providers
+
+Bring your own API key. `ai-tag-debugger` uses the official SDK of each provider:
+
+| Provider | API key variable | Default 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` |
+
+The provider is picked from whichever key is set (Anthropic first if several are). Choose explicitly with `--provider anthropic|openai|gemini` or `"provider"` in the config, and pick another model with `--model`. Navigation asks for low reasoning effort to keep runs cheap; explanations ask for high effort and structured JSON output.
+
+### Any OpenAI-compatible API: Kimi, GLM, DeepSeek, OpenRouter, Ollama and more
+
+Many providers offer an API that works like OpenAI's. Point `ai-tag-debugger` at it with its address and a model id:
+
+```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>
+```
+
+| Provider | `--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 (hundreds of models) | `https://openrouter.ai/api/v1` |
+| Ollama on your computer | `http://localhost:11434/v1` |
+
+Use the model id from your provider's documentation. You can also set `OPENAI_COMPATIBLE_BASE_URL` and `OPENAI_COMPATIBLE_MODEL` instead of the flags, or `"provider"`, `"base_url"` and `"model"` in the config. When the API can't return strict JSON schemas, the explanations fall back to plain JSON mode.
+
+**A word on model choice.** The AI browses by calling tools, one step at a time, for 5 to 30 steps. Models differ a lot in how reliably they do that: smaller and local models may click the wrong thing, loop, or stop early. The checks stay correct whatever the model does, because they come from the captured hits, but a journey that doesn't finish can't show its later events. If a model struggles, try a larger one, a ready-made journey with a short goal, or `--max-steps`. The Anthropic, OpenAI and Gemini defaults are the tested ones.
+
+Adding a native provider means implementing two functions in [`src/providers.js`](src/providers.js): a tool-calling conversation and a structured JSON call.
+
+## Quick start
+
+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
+```
+
+Try it on the included demo shop. It has three deliberate tracking bugs:
+
+```bash
+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
+```
+
+No API key yet? Replay the fixed steps without any AI model:
+
+```bash
+node src/cli.js run --config examples/demo.config.json --scripted --no-ai --out reports/demo
+```
+
+## Choose what to test
+
+You don't need a config file to start. Pick ready-made journeys, describe your own in plain language, and narrow the check to the events you care about:
+
+```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
+```
+
+| Ready-made journey | What the AI does | Events it expects |
+|---|---|---|
+| `purchase` (or `checkout`) | Product → cart → checkout → order with the test payment option | GA4 `view_item`, `add_to_cart`, `begin_checkout`, `purchase`; Meta `AddToCart`, `InitiateCheckout`, `Purchase` |
+| `add_to_cart` (or `cart`) | Opens a product and adds it to the cart | GA4 `view_item`, `add_to_cart`; Meta `AddToCart` |
+| `sign_up` (or `signup`, `register`) | Creates an account with test data | GA4 `sign_up`; Meta `CompleteRegistration` |
+| `lead` (or `contact`, `form`) | Fills in and sends a contact, quote or demo form | GA4 `generate_lead`; Meta `Lead` |
+| `search` | Searches the site and opens a result | GA4 `search` with `search_term`; Meta `Search` |
+
+`--journey` also picks journeys from your config by id. With a config, ready-made journeys add their events to your plan.
+
+### Keeping API usage down
+
+Each browsing step is one model call, so usage grows with **journeys × viewports × steps**, plus one call at the end to explain the findings. The checks themselves never call the model.
+
+- **Run only the journeys you need.** This is the biggest saving: `--journey add_to_cart` instead of the full `purchase` journey takes a few steps instead of ten or more.
+- **Run one viewport.** `--viewport mobile` halves the calls compared with desktop and mobile.
+- **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.
+- **Use a chat app.** Over MCP, the chat app's own model does the browsing, so no API key is used at all.
+
+## Configure your site
+
+`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."
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `site` | Base URL. Use staging when you can. |
+| `plan` | Measurement plan: a file path or an inline object (below). Optional with ready-made journeys. |
+| `gtm_container` | Optional GTM container export (Admin → Export container), so explanations can name tags and triggers. |
+| `viewports` | `desktop` and/or `mobile`. |
+| `journeys` | Optional when you pick ready-made journeys with `--journey` or describe one with `--goal`. |
+| `journeys[].goal` | What the AI should do, in plain language. |
+| `journeys[].start` | Optional start path (default `/`). |
+| `journeys[].steps` | Optional fixed steps for `--scripted` runs: `{ "action": "click", "selector": "#add-to-cart" }`. |
+| `allowed_hosts` | Other hosts journeys may visit, e.g. `["checkout.payments-provider.com"]` for a hosted checkout. The browser otherwise stays on the `site` host and its subdomains. Same as `--allow-host`. |
+| `providers` | Tracking providers to check, e.g. `["ga4", "meta"]`. Default `["ga4", "google_ads", "meta", "tiktok"]`. Same as `--providers`. |
+| `block_hits` | Default `true`. Set to `false` to let hits reach your real endpoints. |
+| `language` | Report language, `en` (default) or `tr`. Same as `--lang`. |
+| `keep_bodies` | Default `false`. Set to `true` to store tracking requests as sent, without redacting user data. Same as `--keep-bodies`. |
+| `branding` | Default `true`. Set to `false` to leave the Analitik İşler logo and the "Generated by AI Tag Debugger · analitikisler.com" line out of the reports. Same as `--no-branding`, or `branding: false` on the MCP `finish_audit` and `run_audit` tools. |
+| `provider` | Optional: `anthropic`, `openai`, `gemini` or `openai-compatible`. Same as `--provider`. |
+| `base_url`, `model` | Optional: the API address and model id, e.g. for `openai-compatible`. Same as `--base-url` and `--model`. |
+
+`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` is `ga4`, `google_ads`, `meta` or `tiktok`. `journeys` limits where an event is expected (default: every journey). Set `allow_multiple: true` for events that may legitimately fire more than once per action.
+
+## 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]
+```
+
+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:
+
+- `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.
+
+  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.
+- `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.
+
+Reports end with a credit line, "Generated by AI Tag Debugger · analitikisler.com", where the domain is a plain link (no images, no tracking, and no referrer, so report URLs aren't leaked). `--no-branding` removes it along with the logo.
+
+Use `--lang tr` for a Turkish report. Finding texts, headings, and the model's explanations and fixes are all written in Turkish, and the agent describes its steps in Turkish too.
+
+## Use it from your AI chat app (MCP)
+
+`ai-tag-debugger mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io) server. Your chat app's model then runs the audit itself: you ask "check the tracking on the checkout of staging.myshop.com" and it opens the browser, clicks through, and explains the findings in the chat. No API key is needed, because the app's own model does the thinking.
+
+Tools the server offers:
+
+| Tool | What it does |
+|---|---|
+| `start_audit` | Opens a fresh browser on a URL and starts recording all tracking. Pass a ready-made journey (`purchase`, `sign_up`, …) to get its goal and expected events, and `providers` to choose what to check. The assistant asks you which platforms to check first. |
+| `browser_action` | One click, fill, select, goto, scroll or wait. Returns the page and the tracking hits that step sent. |
+| `get_page` | Shows the current page. |
+| `finish_audit` | Checks everything against your measurement plan (JSON) or the ready-made journey's events, optionally only the `events` you name, and writes the full HTML report with the timeline. |
+| `run_audit` | Runs a config file end to end (local only). |
+
+The browser runs on the computer where the server runs, so it can reach your staging and `localhost` sites. Tracking requests are answered locally as usual.
+
+### 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`):
+
+```json
+{
+  "mcpServers": {
+    "ai-tag-debugger": {
+      "command": "node",
+      "args": ["/path/to/ai-tag-debugger/src/cli.js", "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`.
+
+### Apps that connect to a URL: ChatGPT, Gemini
+
+These apps connect to MCP servers over HTTPS (in ChatGPT, through developer mode connectors, depending on your plan). Start the server in HTTP mode and expose it with a tunnel:
+
+```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>
+```
+
+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.
+
+In HTTP mode, the server is more locked down than locally:
+
+- It doesn't read measurement plans or configs from your disk (pass the plan as JSON text in the chat), and `run_audit` isn't offered. It only serves the reports it wrote itself.
+- The browser opens only `http` and `https` pages, and refuses `localhost` and private network addresses (such as `192.168.x.x` or `169.254.169.254`), so the URL can't be used to look into your network. All browser traffic, WebSockets included, goes through a small built-in proxy that resolves each host once and connects only to the address it checked, so a DNS answer that changes mid-audit can't get around the check. To audit a local staging site this way anyway, start the server with `--allow-private-network`.
+- Audits left open for 15 minutes are closed, and request bodies are limited to 1 MB.
+
+A hosted server, so you don't need a tunnel, is part of the [Analitik İşler](https://analitikisler.com) Cloud version.
+
+## Safety
+
+- The agent is told to use obvious test data and **never to enter real payment details**. If a journey needs a real payment or account, it stops and reports that instead.
+- Tracking requests to the platforms listed in [How it works](#how-it-works) are answered locally by default, so those analytics and ad accounts don't receive test conversions.
+- The browser stays on the audited site and its subdomains, plus any `allowed_hosts`. It opens only `http` and `https` pages.
+- The model is told that page content is data, never instructions. A prompt rule can't guarantee a model is never misled, so the navigation limits above contain what a misled model can do.
+- The browser runs without your API keys and other secrets in its environment.
+- **User data sent for ad matching is redacted** before it is stored in `capture.json` or shown in the report: emails, phone numbers, names, addresses and user ids in GA4 and Google Ads enhanced conversions (`em`, `ph`, `uid`, …), Meta advanced matching (`ud[*]`, `udff[*]`), TikTok `context.user`, and the `user_data` the site pushes to the dataLayer for enhanced conversions. Any value that looks like an email address is redacted whatever its field is called. Each value becomes a marker such as `[redacted: 64 chars, looks hashed]`, and a value that wasn't hashed is reported as a personal data risk. `--keep-bodies` (`"keep_bodies": true`) stores requests as sent, for debugging.
+- Stored request bodies are capped at 32 KB per request and 2 MB per journey. Past that, the report says the body wasn't stored.
+- Only run it against sites you own or are authorized to test.
+- Hosting the HTTP server for other people? Also block private and cloud metadata address ranges at the network level (an egress firewall or an isolated network), as defense in depth.
+
+## Roadmap
+
+- Consent Check: deeper audits of cookie banners and Consent Mode v2 against GDPR/KVKK.
+- Measurement Plan: draft a plan and dataLayer spec from a URL.
+- Hosted version with scheduled runs, deploy webhooks, a hosted MCP server and multi-site dashboards for agencies at [analitikisler.com](https://analitikisler.com).
+
+## Development
+
+```bash
+npm test   # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
+```
+
+The end-to-end tests use fake model clients, so they run without an API key.
+
+## Hosted version
+
+For hosted runs, scheduling and agency dashboards, see [analitikisler.com](https://analitikisler.com).
+
+## License
+
+MIT © Analitik İşler

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.2",
+  "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"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "demo:serve": "node examples/serve.js",
+    "demo": "node src/cli.js run --config examples/demo.config.json --scripted --out reports/demo"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "analytics",
+    "ga4",
+    "google-tag-manager",
+    "tracking",
+    "qa",
+    "consent-mode",
+    "ai-agent",
+    "mcp",
+    "mcp-server",
+    "claude",
+    "openai",
+    "gemini",
+    "playwright",
+    "tag-debugger",
+    "gtm-debugger"
+  ],
+  "license": "MIT",
+  "author": "Analitik İşler (https://analitikisler.com)",
+  "homepage": "https://github.com/analitikisler/ai-tag-debugger#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/analitikisler/ai-tag-debugger.git"
+  },
+  "bugs": {
+    "url": "https://github.com/analitikisler/ai-tag-debugger/issues"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.110.0",
+    "@google/genai": "^2.28.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "openai": "^7.30.1",
+    "playwright": "1.56.1",
+    "zod": "^4.6.5"
+  }
+}