@analitikisler/ai-tag-debugger 0.22.6 → 0.22.7

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.22.7 (2026-11-04)
+
+- Audits can run in your own Google Chrome. Start Chrome with a debugging port and a profile folder for audits (README: Using your own Chrome), then add `--connect http://127.0.0.1:9222` to `aitd run` or `aitd plan`, or set `connect` in the config or on a local MCP server's `start_audit`. Each journey gets a fresh private window in that Chrome, as clean as the tool's own browser, which closes when the journey ends while Chrome keeps running. Capture, the answered tracking requests, the host limits and logins work as usual. Only a Chrome on the same computer is accepted, an HTTP MCP server never connects to one, and when no Chrome answers, the message gives the command that starts it.
+
 ## 0.22.6 (2026-11-04)
 
 - Journeys can log in. Set a test account in `AITD_LOGIN_EMAIL` (or `AITD_LOGIN_USERNAME`) and `AITD_LOGIN_PASSWORD`: the model fills login forms with the placeholders `{{login.email}}`, `{{login.username}}` and `{{login.password}}`, and the browser types the real values, only into the audited site's pages, never into a frame from another site. The values are turned back into their placeholders in everything the tool keeps or shows (page views, steps, hits, dataLayer pushes, network calls, saved steps and reports), a password field's value is never read into the page view, and the browser doesn't get them in its environment. Over MCP, `start_audit` says whether a test account is set up.

package/README.md

@@ -421,6 +421,21 @@ The model never sees them. It fills login forms with the placeholders `{{login.e
 
 **A saved session**, for a login that needs a person: a CAPTCHA, a code sent to a phone, or single sign-on. `aitd login --site https://yourshop.com` opens the site in a browser window; log in by hand, press Enter in the terminal, and the session (cookies and storage) is saved to `aitd/<domain>/session.json`, readable only by you. `aitd run … --session saved`, the config's `session_file`, or `session: "saved"` on a local MCP server's `start_audit` start every journey logged in. The file holds a live login: keep it private, and save it again when the login expires.
 
+### Using your own Chrome
+
+Audits normally run in the tool's own Chromium. To watch them in your own Google Chrome instead, on your computer's own network, start Chrome with a debugging port and a profile folder for audits (Chrome refuses remote debugging on your everyday profile, and a folder of its own keeps audits away from it):
+
+```bash
+# macOS
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/aitd-chrome"
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\aitd-chrome"
+# Linux
+google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/aitd-chrome"
+```
+
+Then add `--connect http://127.0.0.1:9222` to `aitd run` or `aitd plan` (or `connect` in the config, or `connect` on a local MCP server's `start_audit`). Each journey opens a fresh private window in that Chrome, as clean as the tool's own browser, so every audit is a first visit with no cookies or consent choice left over; the window closes when the journey ends, and Chrome keeps running. Everything else works as usual: tracking requests are answered inside the browser, the site's host limits apply, and a [test account or saved session](#logging-in) logs in. Only a Chrome on the same computer (`127.0.0.1` or `localhost`) is accepted, and an HTTP MCP server never connects to one.
+
 Not sure what to test? `aitd plan --site https://yoursite.com` drafts a measurement plan, and `--against latest` checks the site against it.
 
 ### Keeping API usage down
@@ -515,6 +530,7 @@ The file holds one entry per finding, with a `key` the run matches on (the check
 | `journeys[].steps` | Optional fixed steps for `--scripted` runs: `{ "action": "click", "selector": "#add-to-cart" }`. Without them, `--scripted` repeats the steps of the site's last completed run of the journey. |
 | `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`. |
 | `session_file` | A session saved with `aitd login`, so every journey starts logged in: `"saved"` for the site's own, or a file path. See [Logging in](#logging-in). |
+| `connect` | Your own Chrome's debugging address, e.g. `http://127.0.0.1:9222`: each journey runs in a fresh window of it. See [Using your own Chrome](#using-your-own-chrome). |
 | `providers` | Tracking platforms to check, e.g. `["ga4", "meta"]`. Default `["ga4", "google_ads", "meta", "tiktok"]`, plus any other platform the site sends to while this is unset. Same as `--platforms`. |
 | `campaign_checks` | Default `true`. Each run opens the first page like an ad click (UTM parameters, `gclid`, `fbclid`, or the ones already in the start address) and checks they survive redirects and reach the hits. Set to `false` to open the plain address. |
 | `block_hits` | Default `true`. Set to `false` to let hits reach your real endpoints. |
@@ -569,7 +585,7 @@ aitd run --site <url> (--against <plan> | --journey <id> | --goal "<text>") [--c
          [--max-steps <n>] [--viewport desktop|mobile] [--concurrency <n>] [--platforms <list>] [--data-dir <dir>]
          [--provider anthropic|openai|gemini|openai-compatible] [--model <id>] [--lang en|tr] [--headed]
          [--fail-on broken|risk|warning|never] [--baseline <file>] [--update-baseline]
-         [--scripted] [--no-ai] [--save-site <dir>] [--save-steps <file>] [--session saved|<file>]
+         [--scripted] [--no-ai] [--save-site <dir>] [--save-steps <file>] [--session saved|<file>] [--connect <url>]
 aitd replay <dir>... [--update] [--out <dir>]
 aitd mcp [--http] [--port <n>] [--host <addr>] [--token <secret>] [--public-url <https url>] [--reports <dir>]
          [--allow-private-network] [--allow-live]
@@ -614,6 +630,7 @@ aitd history --site <url> [--limit <n>] [--json] [--lang en|tr] [--data-dir <dir
 | `--allow-host <host>` | run | Another host journeys may visit (repeatable). Same as `allowed_hosts`. |
 | `--session saved\|<file>` | run | Start every journey logged in, from the session `aitd login` saved (`saved`) or a session file. Same as `session_file`. See [Logging in](#logging-in). |
 | `--save <file>` | login | Where `aitd login` saves the session (default `aitd/<domain>/session.json`). |
+| `--connect <url>` | run, plan | Run in your own Chrome, started with a debugging port, e.g. `http://127.0.0.1:9222`. Same as `connect`. See [Using your own Chrome](#using-your-own-chrome). |
 | `--keep-bodies` | run | Store tracking requests as sent, without redacting user data. |
 | `--no-branding` | plan, run | Leave the logo and credit line out of the reports and `plan.html`. |
 | `--http`, `--port`, `--host`, `--token`, `--public-url`, `--reports`, `--allow-private-network`, `--allow-live` | mcp | See the MCP section below. |
@@ -683,7 +700,7 @@ Tools the server offers:
 |---|---|
 | `make_plan` | Drafts a tracking plan for a site (what should be tracked), the same as `aitd plan --site`. Pass `topic` (`custom-events`, `ecommerce`, `forms`, `consent`) to limit it to one kind of event. The plan is saved and its ID can be given as `against` to `finish_audit`. It uses the AI provider configured on the computer that runs the server and takes a few minutes. |
 | `what_changed` | Returns only the "since last run" diff for a site: the problems fixed and the new ones in its newest saved run (`aitd run`) compared with the run before. No browser and no AI. Pass `language` for a Turkish answer. |
-| `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 the platforms to check. The assistant asks you which platforms to check first. `live: true` lets the tracking requests through to the site's real accounts, to check them in GA4 Realtime or DebugView, Meta Events Manager or Tag Assistant; the test traffic then shows in the site's reports, and the results and the report say the run was live. Over HTTP the server needs `--allow-live` for it. The first page opens the way an ad click does, with test campaign parameters (`utm_source=aitd`, `gclid=aitd-gclid`, `fbclid=aitd-fbclid`, …), so `finish_audit` checks that they survive redirects and reach the hits; `campaign: false` opens the URL as given, and `campaign: {"utm_source": "newsletter", "gclid": "test123"}` uses your own values. A test account set on the server's computer is used through its placeholders, and `session: "saved"` starts from the session `aitd login` saved (local servers only); see [Logging in](#logging-in). |
+| `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 the platforms to check. The assistant asks you which platforms to check first. `live: true` lets the tracking requests through to the site's real accounts, to check them in GA4 Realtime or DebugView, Meta Events Manager or Tag Assistant; the test traffic then shows in the site's reports, and the results and the report say the run was live. Over HTTP the server needs `--allow-live` for it. The first page opens the way an ad click does, with test campaign parameters (`utm_source=aitd`, `gclid=aitd-gclid`, `fbclid=aitd-fbclid`, …), so `finish_audit` checks that they survive redirects and reach the hits; `campaign: false` opens the URL as given, and `campaign: {"utm_source": "newsletter", "gclid": "test123"}` uses your own values. A test account set on the server's computer is used through its placeholders, and `session: "saved"` starts from the session `aitd login` saved (local servers only); see [Logging in](#logging-in). `connect` runs it in a fresh window of your own Chrome (local servers only; see [Using your own Chrome](#using-your-own-chrome)). |
 | `browser_action` | One click, fill, select, goto, scroll or wait. Returns the step number, the page and the tracking hits that step sent, each with an `[h]` number, its consent (from `gcs`, and `gcd` for `ad_user_data` and `ad_personalization`) and the ids and flags GA4 sends with it (`cid`, `sid`, `gcs`, `gcd`, `_fv`, `_ss`, `_nsi`, …), its dataLayer pushes (Consent Mode commands in full as `key=value`, page addresses never cut) and the calls it read no event from, such as Consent Mode pings with their `gcs`, `gcd` and click ids (`gclid`, `gclid=0 (redacted)` when ads data redaction blanks it, `gclaw` from `_gcl_aw`), and the cookies the step added, changed or removed, by name, with the GA4 client id and whether `_gcl_aw` and `_fbc` hold the landing click ids when that changes. A page_view that arrives during a later wait or scroll is listed on the step that loaded its page, marked late. The page view is compact by default, since long sessions lose their oldest results: up to 40 elements above or below the screen, and the page text or element list replaced by a note when they haven't changed since the last view. Pass `detail: "full"` for everything. |
 | `get_page` | Shows the current page, in full: every element and the whole page text. |
 | `get_hit` | Shows one hit in full, by its `step` and `[h]` number: every parameter its request carried, its place in a batched request, where it was sent, and `gcd` decoded per consent signal (default and update). |

package/README.tr.md

@@ -421,6 +421,21 @@ Model bunları hiç görmez. Giriş formlarını `{{login.email}}`, `{{login.use
 
 **Kaydedilmiş bir oturum**, bir insan gerektiren girişler için: bir CAPTCHA, telefona gelen bir kod ya da tek oturum açma (SSO). `aitd login --site https://magazaniz.com` siteyi bir tarayıcı penceresinde açar; elle giriş yapın, terminalde Enter'a basın; oturum (çerezler ve depolama) yalnızca sizin okuyabileceğiniz `aitd/<alan-adı>/session.json` dosyasına kaydedilir. `aitd run … --session saved`, yapılandırmadaki `session_file` ya da yerel bir MCP sunucusunda `start_audit` için `session: "saved"` her yolculuğu giriş yapılmış olarak başlatır. Dosya canlı bir oturum tutar: gizli tutun ve oturum sona erdiğinde yeniden kaydedin.
 
+### Kendi Chrome'unuzu kullanmak
+
+Denetimler normalde aracın kendi Chromium'unda çalışır. Bunun yerine onları kendi Google Chrome'unuzda, bilgisayarınızın kendi ağında izlemek için Chrome'u bir hata ayıklama bağlantı noktası ve denetimlere ayrılmış bir profil klasörüyle başlatın (Chrome günlük profilinizde uzaktan hata ayıklamaya izin vermez; ayrı bir klasör de denetimleri ondan uzak tutar):
+
+```bash
+# macOS
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/aitd-chrome"
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\aitd-chrome"
+# Linux
+google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/aitd-chrome"
+```
+
+Ardından `aitd run` ya da `aitd plan` komutuna `--connect http://127.0.0.1:9222` ekleyin (ya da yapılandırmada `connect`, yerel bir MCP sunucusunda `start_audit` için `connect`). Her yolculuk o Chrome'da aracın kendi tarayıcısı kadar temiz, yeni bir gizli pencere açar; böylece her denetim, kalan çerez ya da onay seçimi olmayan bir ilk ziyarettir. Yolculuk bitince pencere kapanır, Chrome çalışmaya devam eder. Geri kalan her şey her zamanki gibi çalışır: takip istekleri tarayıcının içinde yanıtlanır, sitenin ana makine sınırları geçerlidir ve bir [test hesabı ya da kaydedilmiş oturum](#giriş-yapmak) giriş yapar. Yalnızca aynı bilgisayardaki bir Chrome (`127.0.0.1` ya da `localhost`) kabul edilir ve bir HTTP MCP sunucusu hiçbir zaman ona bağlanmaz.
+
 Ne test edeceğinizden emin değil misiniz? `aitd plan --site https://yoursite.com` bir ölçümleme planı taslağı çıkarır, `--against latest` de siteyi buna göre kontrol eder.
 
 ### API kullanımını düşük tutmak
@@ -515,6 +530,7 @@ Dosyada her bulgu için bir kayıt bulunur: çalıştırmanın eşleştirme yapt
 | `journeys[].steps` | `--scripted` çalıştırmaları için isteğe bağlı sabit adımlar: `{ "action": "click", "selector": "#add-to-cart" }`. Bunlar yoksa `--scripted`, sitenin o yolculuğu son tamamlayan çalıştırmasının adımlarını tekrarlar. |
 | `allowed_hosts` | Yolculukların ziyaret edebileceği başka ana makineler, örneğin barındırılan bir ödeme için `["checkout.payments-provider.com"]`. Tarayıcı aksi halde `site` ana makinesinde ve alt alan adlarında kalır. `--allow-host` ile aynıdır. |
 | `session_file` | `aitd login` ile kaydedilmiş bir oturum; her yolculuk giriş yapılmış olarak başlar: sitenin kendi oturumu için `"saved"` ya da bir dosya yolu. Bkz. [Giriş yapmak](#giriş-yapmak). |
+| `connect` | Kendi Chrome'unuzun hata ayıklama adresi, örneğin `http://127.0.0.1:9222`: her yolculuk onun yeni bir penceresinde çalışır. Bkz. [Kendi Chrome'unuzu kullanmak](#kendi-chromeunuzu-kullanmak). |
 | `providers` | Kontrol edilecek takip platformları, örneğin `["ga4", "meta"]`. Varsayılan `["ga4", "google_ads", "meta", "tiktok"]`; bu ayar boşken sitenin gönderdiği diğer platformlar da eklenir. `--platforms` ile aynıdır. |
 | `campaign_checks` | Varsayılan `true`. Her çalıştırma ilk sayfayı bir reklam tıklaması gibi açar (UTM parametreleri, `gclid`, `fbclid` ya da başlangıç adresinde zaten olanlar) ve bunların yönlendirmelerden geçip isteklere ulaştığını denetler. Düz adresi açmak için `false` yapın. |
 | `block_hits` | Varsayılan `true`. Takip isteklerinin gerçek uç noktalarınıza ulaşmasına izin vermek için `false` yapın. |
@@ -569,7 +585,7 @@ aitd run --site <url> (--against <plan> | --journey <id> | --goal "<metin>") [--
          [--max-steps <n>] [--viewport desktop|mobile] [--concurrency <n>] [--platforms <liste>] [--data-dir <dir>]
          [--provider anthropic|openai|gemini|openai-compatible] [--model <id>] [--lang en|tr] [--headed]
          [--fail-on broken|risk|warning|never] [--baseline <dosya>] [--update-baseline]
-         [--scripted] [--no-ai] [--save-site <dir>] [--save-steps <dosya>] [--session saved|<dosya>]
+         [--scripted] [--no-ai] [--save-site <dir>] [--save-steps <dosya>] [--session saved|<dosya>] [--connect <url>]
 aitd replay <dir>... [--update] [--out <dir>]
 aitd mcp [--http] [--port <n>] [--host <adres>] [--token <gizli>] [--public-url <https url>] [--reports <dir>]
          [--allow-private-network] [--allow-live]
@@ -614,6 +630,7 @@ aitd history --site <url> [--limit <n>] [--json] [--lang en|tr] [--data-dir <dir
 | `--allow-host <ana makine>` | run | Yolculukların ziyaret edebileceği başka bir ana makine (tekrarlanabilir). `allowed_hosts` ile aynıdır. |
 | `--session saved\|<dosya>` | run | Her yolculuğu, `aitd login`'in kaydettiği oturumdan (`saved`) ya da bir oturum dosyasından giriş yapılmış olarak başlatır. `session_file` ile aynı. Bkz. [Giriş yapmak](#giriş-yapmak). |
 | `--save <dosya>` | login | `aitd login`'in oturumu nereye kaydedeceği (varsayılan `aitd/<alan-adı>/session.json`). |
+| `--connect <url>` | run, plan | Bir hata ayıklama bağlantı noktasıyla başlatılmış kendi Chrome'unuzda çalıştırır, örneğin `http://127.0.0.1:9222`. `connect` ile aynı. Bkz. [Kendi Chrome'unuzu kullanmak](#kendi-chromeunuzu-kullanmak). |
 | `--keep-bodies` | run | Takip isteklerini gönderildiği gibi, kullanıcı verisi gizlenmeden sakla. |
 | `--no-branding` | plan, run | Logo ve kredi satırını raporlardan ve `plan.html` dosyasından çıkar. |
 | `--http`, `--port`, `--host`, `--token`, `--public-url`, `--reports`, `--allow-private-network`, `--allow-live` | mcp | Aşağıdaki MCP bölümüne bakın. |
@@ -683,7 +700,7 @@ Sunucunun sunduğu araçlar:
 |---|---|
 | `make_plan` | Bir site için takip planı çıkarır (neyin takip edilmesi gerektiği), `aitd plan --site` ile aynıdır. Yalnızca bir tür event için sınırlamak üzere `topic` verin (`custom-events`, `ecommerce`, `forms`, `consent`). Plan kaydedilir ve kimliği `finish_audit` için `against` olarak verilebilir. Sunucuyu çalıştıran bilgisayarda ayarlı yapay zekâ sağlayıcısını kullanır ve birkaç dakika sürer. |
 | `what_changed` | Bir site için yalnızca "son çalıştırmadan bu yana" farkını döndürür: kayıtlı son çalıştırmanın (`aitd run`) bir öncekine göre düzelen ve yeni sorunları. Tarayıcı ve yapay zekâ kullanmaz. Türkçe yanıt için `language` verin. |
-| `start_audit` | Bir URL'de yeni bir tarayıcı açar ve tüm takibi kaydetmeye başlar. Hedefini ve beklenen event'lerini almak için hazır bir yolculuk (`purchase`, `sign_up`, …) verin; kontrol edilecek platformları seçmek için `providers` verin. Asistan önce hangi platformların kontrol edileceğini size sorar. `live: true`, takip isteklerini sitenin gerçek hesaplarına geçirir; böylece GA4 Realtime ya da DebugView, Meta Events Manager veya Tag Assistant'ta kontrol edilebilirler. Test trafiği o zaman sitenin raporlarında görünür; sonuçlar ve rapor çalıştırmanın canlı olduğunu söyler. HTTP üzerinden sunucunun bunun için `--allow-live` ile başlatılması gerekir. İlk sayfa bir reklam tıklaması gibi, test kampanya parametreleriyle (`utm_source=aitd`, `gclid=aitd-gclid`, `fbclid=aitd-fbclid`, …) açılır; böylece `finish_audit` bunların yönlendirmelerden sağ çıkıp isteklere ulaştığını kontrol eder. `campaign: false` URL'yi olduğu gibi açar, `campaign: {"utm_source": "newsletter", "gclid": "test123"}` ise sizin değerlerinizi kullanır. Sunucunun bilgisayarında ayarlı bir test hesabı yer tutucularıyla kullanılır; `session: "saved"` ise `aitd login`'in kaydettiği oturumdan başlar (yalnızca yerel sunucular); bkz. [Giriş yapmak](#giriş-yapmak). |
+| `start_audit` | Bir URL'de yeni bir tarayıcı açar ve tüm takibi kaydetmeye başlar. Hedefini ve beklenen event'lerini almak için hazır bir yolculuk (`purchase`, `sign_up`, …) verin; kontrol edilecek platformları seçmek için `providers` verin. Asistan önce hangi platformların kontrol edileceğini size sorar. `live: true`, takip isteklerini sitenin gerçek hesaplarına geçirir; böylece GA4 Realtime ya da DebugView, Meta Events Manager veya Tag Assistant'ta kontrol edilebilirler. Test trafiği o zaman sitenin raporlarında görünür; sonuçlar ve rapor çalıştırmanın canlı olduğunu söyler. HTTP üzerinden sunucunun bunun için `--allow-live` ile başlatılması gerekir. İlk sayfa bir reklam tıklaması gibi, test kampanya parametreleriyle (`utm_source=aitd`, `gclid=aitd-gclid`, `fbclid=aitd-fbclid`, …) açılır; böylece `finish_audit` bunların yönlendirmelerden sağ çıkıp isteklere ulaştığını kontrol eder. `campaign: false` URL'yi olduğu gibi açar, `campaign: {"utm_source": "newsletter", "gclid": "test123"}` ise sizin değerlerinizi kullanır. Sunucunun bilgisayarında ayarlı bir test hesabı yer tutucularıyla kullanılır; `session: "saved"` ise `aitd login`'in kaydettiği oturumdan başlar (yalnızca yerel sunucular); bkz. [Giriş yapmak](#giriş-yapmak). `connect` onu kendi Chrome'unuzun yeni bir penceresinde çalıştırır (yalnızca yerel sunucular; bkz. [Kendi Chrome'unuzu kullanmak](#kendi-chromeunuzu-kullanmak)). |
 | `browser_action` | Tek bir tıklama, doldurma, seçme, gitme, kaydırma ya da bekleme. Adım numarasını, sayfayı, o adımın gönderdiği takip isteklerini (her biri bir `[h]` numarası, onay durumu — `gcs`'den, `ad_user_data` ve `ad_personalization` için `gcd`'den — ve GA4'ün onunla gönderdiği kimlik ve işaretlerle: `cid`, `sid`, `gcs`, `gcd`, `_fv`, `_ss`, `_nsi`, …), dataLayer push'larını (Consent Mode komutları `anahtar=değer` olarak eksiksiz, sayfa adresleri hiç kesilmeden) ve event olarak okunmayan çağrıları (ör. `gcs`, `gcd` ve tıklama kimlikleriyle Consent Mode ping'leri: `gclid`, reklam verisi karartma açıksa `gclid=0 (redacted)`, `_gcl_aw`'dan `gclaw`), ayrıca adımın eklediği, değiştirdiği ya da sildiği çerezleri adlarıyla, değiştiğinde de GA4 istemci kimliğini ve `_gcl_aw` ile `_fbc`'nin açılış tıklama kimliklerini tutup tutmadığını döndürür. Sonraki bir bekleme ya da kaydırma sırasında gelen page_view, sayfasını yükleyen adımda gecikmeli olarak işaretlenip gösterilir. Uzun oturumlar en eski sonuçlarını kaybettiği için sayfa görünümü varsayılan olarak kısadır: ekranın üstünde ya da altında en fazla 40 öğe; sayfa metni ya da öğe listesi son görünümden beri değişmediyse yerine bir not. Hepsi için `detail: "full"` verin. |
 | `get_page` | Geçerli sayfayı eksiksiz gösterir: her öğe ve sayfanın tüm metni. |
 | `get_hit` | Bir isteği `step` ve `[h]` numarasıyla eksiksiz gösterir: isteğin taşıdığı her parametre, toplu bir istekteki sırası, nereye gönderildiği ve her onay sinyali için çözümlenmiş `gcd` (varsayılan ve güncelleme). |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
   "mcpName": "io.github.analitikisler/ai-tag-debugger",
-  "version": "0.22.6",
+  "version": "0.22.7",
   "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/agent.js

@@ -205,7 +205,7 @@ export const harName = (journeyId, viewport) => `${String(journeyId).replace(/[^
 export async function runJourney(config, journey, viewport, opts = {}) {
   const har = (dir) => (dir ? path.join(dir, harName(journey.id, viewport)) : undefined);
   const session = new AuditSession({
-    viewport, site: config.site, allowedHosts: config.allowed_hosts, storageState: config.session_file, providers: config.providers, detect: config.detect_providers, keepBodies: config.keep_bodies === true,
+    viewport, site: config.site, allowedHosts: config.allowed_hosts, storageState: config.session_file, connect: config.connect, providers: config.providers, detect: config.detect_providers, keepBodies: config.keep_bodies === true,
     blockHits: config.block_hits !== false, headless: !opts.headed, recordHar: har(opts.saveSite), replayHar: har(opts.replaySite), log: opts.log,
   });
   try {

package/src/browser.js

@@ -53,6 +53,36 @@ export const VIEWPORTS = {
 // Runs in the page before any site script: reports every dataLayer push
 // (including gtag consent commands) to Node through an exposed binding, so the
 // log survives page navigations.
+// How to start Chrome for --connect, per system: a debugging port, and a profile folder of its own, which Chrome
+// requires for remote debugging and which keeps the audits away from the everyday profile.
+export const CHROME_START = {
+  darwin: `"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/aitd-chrome"`,
+  win32: `"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\\aitd-chrome"`,
+  linux: `google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/aitd-chrome"`,
+};
+
+/**
+ * Connects to a Chrome the user started with a debugging port. Only a Chrome on this computer: the address must be
+ * a loopback one, so a config or a chat can't point the tool at someone else's browser.
+ */
+export async function connectToChrome(endpoint, { connect = (url) => chromium.connectOverCDP(url, { timeout: 10_000 }), platform = process.platform } = {}) {
+  let u;
+  try {
+    u = new URL(String(endpoint));
+  } catch {
+    throw new Error(`"${endpoint}" is not an address. Use the debugging address Chrome was started with, e.g. http://127.0.0.1:9222`);
+  }
+  if (!["http:", "https:", "ws:", "wss:"].includes(u.protocol) || !["127.0.0.1", "localhost", "[::1]", "::1"].includes(u.hostname)) {
+    throw new Error(`Only a Chrome on this computer can be connected to (127.0.0.1 or localhost), not ${u.host}.`);
+  }
+  try {
+    return await connect(u.href);
+  } catch (err) {
+    if (!/ECONNREFUSED|ECONNRESET|socket hang up|404|retrieving websocket url/i.test(String(err?.message))) throw err;
+    throw new Error(`No Chrome answers at ${u.href}. Start Chrome with a debugging port and a profile folder for audits, then try again:\n  ${CHROME_START[platform] ?? CHROME_START.linux}`);
+  }
+}
+
 /** A page address without its hash, for matching page_location to navigations. */
 const pageKey = (url) => String(url ?? "").split("#")[0];
 /** The host of a URL, or null. */
@@ -623,6 +653,18 @@ export class AuditSession {
     if (this.opts.storageState && !existsSync(this.opts.storageState)) throw new Error(`No saved login session at ${this.opts.storageState}. Save one with: aitd login --site <url>`);
     const device = VIEWPORTS[this.opts.viewport];
     if (!device) throw new Error(`Unknown viewport "${this.opts.viewport}". Use: ${Object.keys(VIEWPORTS).join(", ")}`);
+    if (this.opts.connect) {
+      // The user's own Chrome: only the browser is theirs. The audit gets a fresh private window (a new context) in
+      // it, exactly as clean as a launched browser, and close() closes that window and disconnects, leaving Chrome.
+      if (this.opts.blockPrivate) throw new Error("Connecting to your own Chrome works only from the CLI or a local MCP server, not over HTTP.");
+      if (this.opts.replayHar) throw new Error("A saved site replays in the tool's own browser; leave --connect out.");
+      this.browser = await connectToChrome(this.opts.connect);
+    } else await this.launchBrowser();
+    await this.setUpContext(device);
+  }
+
+  /** Launches the tool's own Chromium, through the egress proxy when private addresses are blocked. */
+  async launchBrowser() {
     const launch = { headless: this.opts.headless, env: browserEnv() };
     if (this.opts.blockPrivate) {
       // Every connection, WebSockets included, goes to an address the proxy checked.
@@ -643,6 +685,10 @@ export class AuditSession {
       await installBrowser();
       this.browser = await chromium.launch(launch);
     }
+  }
+
+  /** The audit's own context (fresh cookies and storage, or a saved session) with the capture hooks and routes. */
+  async setUpContext(device) {
     const record = this.opts.recordHar ? { recordHar: { path: this.opts.recordHar, mode: "minimal" } } : {};
     // A session saved with `aitd login`: the browser starts logged in, for sites whose login needs a person.
     const session = this.opts.storageState ? { storageState: this.opts.storageState } : {};

package/src/cli.js

@@ -71,6 +71,7 @@ async function main(args = process.argv.slice(2)) {
       providers: { type: "string", multiple: true },
       "allow-host": { type: "string", multiple: true },
       session: { type: "string" },
+      connect: { type: "string" },
       save: { type: "string" },
       "allow-private-network": { type: "boolean", default: false },
       "allow-live": { type: "boolean", default: false },
@@ -177,7 +178,7 @@ async function main(args = process.argv.slice(2)) {
     const { discoverPlan } = await import("./discover.js");
     const provider = await createProvider({ name: values.provider, model: values.model, baseUrl: values["base-url"] });
     console.log(`Exploring ${values.site} to draft its measurement plan…`);
-    const { plan } = await discoverPlan({ site: values.site, topic: values.topic, provider, maxSteps, headed: values.headed, allowedHosts: values["allow-host"], log: console.log });
+    const { plan } = await discoverPlan({ site: values.site, topic: values.topic, provider, maxSteps, headed: values.headed, allowedHosts: values["allow-host"], connect: values.connect, log: console.log });
     const { id, dir } = await savePlan(plan, { dataDir, site: values.site, branding: !values["no-branding"] });
     const custom = plan.events.filter((e) => e.custom).length;
     const rel = path.relative(process.cwd(), dir);
@@ -236,6 +237,8 @@ async function main(args = process.argv.slice(2)) {
   }
   if (values["keep-bodies"]) loaded.config = { ...loaded.config, keep_bodies: true };
   if (values["allow-host"]?.length) loaded.config = { ...loaded.config, allowed_hosts: [...(loaded.config.allowed_hosts ?? []), ...values["allow-host"]] };
+  // Your own Chrome, started with a debugging port: every journey runs in a fresh window of it.
+  if (values.connect) loaded.config = { ...loaded.config, connect: values.connect };
   // A session saved with `aitd login` ("saved") or a file: every journey starts logged in.
   const sessionArg = values.session ?? loaded.config.session_file;
   if (sessionArg) loaded.config = { ...loaded.config, session_file: resolveSessionFile(sessionArg, { site: loaded.config.site, dataDir: values["data-dir"] ?? DEFAULT_DATA_DIR }) };

package/src/consent.js

@@ -184,7 +184,7 @@ export function scenarioLanding(config, campaign) {
  */
 async function runState(config, state, opts) {
   const session = new AuditSession({
-    viewport: "desktop", site: config.site, allowedHosts: config.allowed_hosts, storageState: config.session_file, providers: config.providers,
+    viewport: "desktop", site: config.site, allowedHosts: config.allowed_hosts, storageState: config.session_file, connect: config.connect, providers: config.providers,
     blockHits: config.block_hits !== false, headless: !opts.headed, ...(opts.blockPrivate ? { blockPrivate: opts.blockPrivate } : {}),
   });
   const landing = scenarioLanding(config, opts.campaign);

package/src/discover.js

@@ -141,13 +141,13 @@ export function toPlan(site, answer, hits = []) {
 /**
  * Lets the AI explore the site (one page per type), then asks it for a measurement plan.
  * With `topic`, exploring and the plan are limited to that kind of event (see TOPICS).
- * @param {{ site: string, topic?: string, provider: any, maxSteps?: number, headed?: boolean, allowedHosts?: string[], viewport?: string, blockPrivate?: boolean, log?: (msg: string) => void }} opts
+ * @param {{ site: string, topic?: string, provider: any, maxSteps?: number, headed?: boolean, allowedHosts?: string[], viewport?: string, blockPrivate?: boolean, connect?: string, log?: (msg: string) => void }} opts
  */
 export async function discoverPlan(opts) {
   const log = opts.log ?? (() => {});
   const topic = TOPICS[checkTopic(opts.topic)];
   const goal = topic ? `${DISCOVER_GOAL}\nThis plan covers only ${opts.topic}: visit just ${topic.explore}, and skip other kinds of page.` : DISCOVER_GOAL;
-  const session = new AuditSession({ viewport: opts.viewport ?? "desktop", site: opts.site, allowedHosts: opts.allowedHosts, headless: !opts.headed, blockPrivate: opts.blockPrivate });
+  const session = new AuditSession({ viewport: opts.viewport ?? "desktop", site: opts.site, allowedHosts: opts.allowedHosts, headless: !opts.headed, blockPrivate: opts.blockPrivate, connect: opts.connect });
   const snapshots = [];
   let outcome;
   try {

package/src/help.js

@@ -43,6 +43,7 @@ Options:
   --lang <code>        Report language: ${Object.keys(LANGUAGES).join(" or ")}
   --headed             Show the browser window
   --session <file>     Start logged in: saved (the session aitd login saved) or a session file
+  --connect <url>      Run in your own Chrome, started with a debugging port (http://127.0.0.1:9222)
   --fail-on <level>    Exit 1 at this level: broken (default), risk, warning, never
   --baseline <file>    Known findings to accept; they don't count toward --fail-on
   --update-baseline    Write the baseline file after the run (creates it)
@@ -74,6 +75,7 @@ Options:
   --site <url>         The site (required)
   --topic <name>       Only plan one kind of event: custom-events, ecommerce, forms or consent
   --headed             Show the browser window
+  --connect <url>      Explore in your own Chrome, started with a debugging port
 
 AI:  --provider <name>   --model <id|cheap>   (default: whichever API key is set)
 

package/src/mcp.js

@@ -442,6 +442,10 @@ export function buildServer(opts) {
           .optional()
           .describe(`Tracking providers to check. Default ${DEFAULT_PROVIDERS.join(", ")} plus any other known platform the site sends to. When given, requests to the others are still answered locally, but they are only counted, not shown or checked.`),
         campaign: campaignSchema().describe(`Open the first page the way an ad click does, so finish_audit checks that the campaign parameters survive redirects and reach the hits. ${CAMPAIGN_DOC}`),
+        connect: z
+          .string()
+          .optional()
+          .describe("Run the audit in a fresh window of the user's own Chrome instead of the tool's browser: the debugging address Chrome was started with, e.g. http://127.0.0.1:9222 (Chrome started with --remote-debugging-port=9222 and its own --user-data-dir). Only a Chrome on the computer running a local server. Use it only when the user asks to see the audit in their Chrome."),
         session: z
           .enum(["saved"])
           .optional()
@@ -449,7 +453,7 @@ export function buildServer(opts) {
         live: z.boolean().optional().describe("Default false: tracking requests are answered locally and never reach the site's accounts. true lets them through to the real analytics and ad accounts, to check them in GA4 Realtime or DebugView, Meta Events Manager or Tag Assistant: the test traffic then shows in the site's reports. Only when the user asks for it."),
       },
     },
-    async ({ site, journey, viewport, allowed_hosts, providers, campaign = true, live = false, session: savedSession }) => {
+    async ({ site, journey, viewport, allowed_hosts, providers, campaign = true, live = false, session: savedSession, connect }) => {
       let url;
       try {
         url = new URL(site);
@@ -468,8 +472,10 @@ export function buildServer(opts) {
         if (live && !opts.allowLive) return fail("Live audits are off on this server: it was started without --allow-live. Leave live out to audit with tracking requests answered locally.");
         // A saved login lives on the computer running the server; over HTTP, a chat elsewhere must not use it.
         if (savedSession && !opts.allowFiles) return fail("A saved login session can only be used on a local server. Leave session out, or log in with the test account during the journey.");
+        // A Chrome on the server's computer belongs to whoever runs it; over HTTP, a chat elsewhere must not drive it.
+        if (connect && !opts.allowFiles) return fail("Connecting to your own Chrome works only on a local server. Leave connect out to use the tool's browser.");
         const storageState = savedSession ? resolveSessionFile("saved", { site: url.href, dataDir: opts.dataDir ?? DEFAULT_DATA_DIR }) : undefined;
-        session = new AuditSession({ viewport: viewport ?? "desktop", site: url.href, allowedHosts: allowed_hosts, providers, blockPrivate: opts.blockPrivate, blockHits: !live, storageState });
+        session = new AuditSession({ viewport: viewport ?? "desktop", site: url.href, allowedHosts: allowed_hosts, providers, blockPrivate: opts.blockPrivate, blockHits: !live, storageState, connect });
       } catch (err) {
         return fail(err.message);
       }
@@ -477,7 +483,7 @@ export function buildServer(opts) {
         await session.start();
       } catch (err) {
         await session.close().catch(() => {});
-        return fail(`Could not start the browser: ${err.message}. If Chromium is missing, run: npx playwright install chromium`);
+        return fail(connect ? `Could not connect to Chrome: ${err.message}` : `Could not start the browser: ${err.message}. If Chromium is missing, run: npx playwright install chromium`);
       }
       const id = randomUUID().slice(0, 8);
       const preset = presetFor(journey);

package/src/schema.js

@@ -69,6 +69,7 @@ export const CONFIG_SCHEMA = z.looseObject({
   journeys: z.array(JOURNEY_SCHEMA).optional(),
   allowed_hosts: names.optional(),
   session_file: text.optional(),
+  connect: text.optional(),
   providers: z.union([names, text], { error: 'must be a list of platforms, e.g. ["ga4", "meta"]' }).optional(),
   detect_providers: flag.optional(),
   campaign_checks: flag.optional(),