@analitikisler/ai-tag-debugger 0.22.4 → 0.22.6

package/src/checks.js

@@ -5,7 +5,7 @@ import { messages } from "./i18n.js";
 import { isOwnAddress } from "./redact.js";
 import { campaignParamsIn } from "./campaign.js";
 import { CONSENT_SIGNALS } from "./parsers.js";
-import { duplicateLoads, loadSources, scriptFailed, splitLayers } from "./containers.js";
+import { containersNotRun, duplicateLoads, loadSources, scriptFailed, splitLayers } from "./containers.js";
 import { messageOutcomes, widgetSummaries, widgetsOf } from "./frames.js";
 
 const platformName = (p) => ({ meta: "Meta", tiktok: "TikTok" })[p] ?? p;
@@ -394,6 +394,23 @@ export function checkRun(plan, run, { lang = "en" } = {}) {
     findings.push({ ...base, severity: "warning", check: "container_failed", step: stepLabel(sc.step), detail: d.containerFailed(sc.id, sc.host, String(sc.status)) });
   }
 
+  // A GTM container downloaded or asked for that never ran. Expected while a consent platform holds it back and the
+  // run never consented; otherwise none of its tags fired.
+  const consented = consentGrantedStep(run) !== null;
+  for (const c of containersNotRun(run)) {
+    findings.push(run.cmp?.vendor && !consented
+      ? { ...base, severity: "info", check: "container_held", step: stepLabel(c.step), detail: d.containerHeld(c.id, run.cmp.vendor) }
+      : { ...base, severity: "warning", check: "container_not_run", step: stepLabel(c.step), detail: d.containerNotRun(c.id, c.kind) });
+  }
+
+  // Logged in with the test account: GA4 hits from then on should carry the site's user ID.
+  if (Number.isInteger(run.loginStep)) {
+    const after = run.hits.filter((h) => h.platform === "ga4" && h.step > run.loginStep);
+    if (after.length && !after.some((h) => h.hasUserId)) {
+      findings.push({ ...base, severity: "info", check: "user_id_missing", platform: "ga4", step: stepLabel(after[0].step), detail: d.userIdMissing(after.length) });
+    }
+  }
+
   // Widgets that tracked on their own, left out of the plan checks: said once per widget, so nothing goes missing silently.
   for (const w of widgetsOf(run.widgetHits ?? [])) {
     const first = (run.widgetHits ?? []).find((h) => h.frame.origin === w.origin);

package/src/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { chmod, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { loadConfig, runAudit } from "./audit.js";
@@ -10,10 +11,48 @@ import { replaySavedSite, writeSavedSteps } from "./replay.js";
 import { readBaseline, writeBaseline } from "./baseline.js";
 import { savePlan } from "./plan.js";
 import { DEFAULT_DATA_DIR } from "./workspace.js";
+import { resolveSessionFile, sessionFileFor } from "./login.js";
 import { commandText, intentToArgs, isSentence, needsWhatToTest, translate } from "./ask.js";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
+/**
+ * `aitd login`: opens the site in a visible browser for the user to log in by hand (a CAPTCHA, two-factor login or
+ * single sign-on are fine), then saves the session (cookies and storage) for runs to start from with --session saved.
+ * The file holds a live login, so only its owner may read it.
+ */
+async function saveLoginSession(values) {
+  if (!values.site) throw new Error("login needs --site <url>: aitd login --site https://www.example.com");
+  try {
+    new URL(values.site);
+  } catch {
+    throw new Error(`"${values.site}" is not a full URL. Use e.g. https://www.example.com`);
+  }
+  const file = path.resolve(values.save ?? sessionFileFor(values.site, values["data-dir"] ?? DEFAULT_DATA_DIR));
+  const { AuditSession } = await import("./browser.js");
+  const session = new AuditSession({ viewport: "desktop", site: values.site, allowedHosts: values["allow-host"], headless: false, login: null });
+  await session.start();
+  try {
+    await session.act({ action: "goto", url: values.site });
+    console.log("Log in to the site in the browser window. When you are logged in, come back here and press Enter (Ctrl+C cancels).");
+    console.log(`The browser stays on ${session.scope.hosts.join(", ")}; for a login on another host (single sign-on), add --allow-host <host>.`);
+    await new Promise((resolve) => {
+      process.stdin.resume();
+      process.stdin.once("data", () => {
+        process.stdin.pause();
+        resolve();
+      });
+    });
+    await mkdir(path.dirname(file), { recursive: true });
+    await session.context.storageState({ path: file });
+    await chmod(file, 0o600);
+    console.log(`Saved the logged-in session to ${file}. It holds a live login: keep it private.`);
+    console.log(`Start a run from it with: aitd run --site ${values.site} --session ${values.save ? file : "saved"} --journey <id>`);
+  } finally {
+    await session.close();
+  }
+}
+
 async function main(args = process.argv.slice(2)) {
   const { values, positionals } = parseArgs({
     args,
@@ -31,6 +70,8 @@ async function main(args = process.argv.slice(2)) {
       platforms: { type: "string", multiple: true },
       providers: { type: "string", multiple: true },
       "allow-host": { type: "string", multiple: true },
+      session: { type: "string" },
+      save: { type: "string" },
       "allow-private-network": { type: "boolean", default: false },
       "allow-live": { type: "boolean", default: false },
       scripted: { type: "boolean", default: false },
@@ -83,6 +124,10 @@ async function main(args = process.argv.slice(2)) {
     await startMcp({ http: values.http, port: values.port ? Number(values.port) : undefined, host: values.host, token: values.token, reportsDir: values.reports, publicUrl: values["public-url"], allowPrivateNetwork: values["allow-private-network"], allowLive: values["allow-live"] });
     return;
   }
+  if (command === "login" && !values.help) {
+    await saveLoginSession(values);
+    return;
+  }
   if (command === "replay" && !values.help) {
     const dirs = positionals.slice(1);
     if (!dirs.length) throw new Error("replay needs the folder of at least one site saved with --save-site.");
@@ -191,6 +236,9 @@ 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"]] };
+  // 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 }) };
   try {
     new URL(loaded.config.site);
   } catch {

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, providers: config.providers,
+    viewport: "desktop", site: config.site, allowedHosts: config.allowed_hosts, storageState: config.session_file, providers: config.providers,
     blockHits: config.block_hits !== false, headless: !opts.headed, ...(opts.blockPrivate ? { blockPrivate: opts.blockPrivate } : {}),
   });
   const landing = scenarioLanding(config, opts.campaign);

package/src/containers.js

@@ -7,6 +7,9 @@
 // Container and destination IDs gtm.js and gtag/js are loaded with.
 const CONTAINER_ID = /^(GTM|G|GT|AW|DC|MC|HA)-[A-Z0-9]+$/;
 
+/** Whether a string is a container or Google tag ID: GTM-…, G-…, GT-…, AW-…, DC-… and the like. */
+export const isContainerId = (id) => CONTAINER_ID.test(String(id));
+
 /**
  * The container a script URL loads, or null: its ID, gtm or gtag, the dataLayer it reads (`l`), the host it
  * came from (Google's, or the site's own through the Google tag gateway or a server container) and the GTM
@@ -148,13 +151,16 @@ export function loadSources(run) {
 
 /**
  * One row per container and source across runs, in the order first seen: { id, script, layer, served, host,
- * environment?, kind, by?, frame?, version?, bytes?, transferBytes?, ms?, failed?, pages, journeys }. frame is the
- * iframe it loaded in; version to failed are its script's answer (see scriptFacts), from the first load in the row.
+ * environment?, kind, by?, frame?, version?, bytes?, transferBytes?, ms?, failed?, ran?, pages, journeys }. frame is
+ * the iframe it loaded in; version to failed are its script's answer (see scriptFacts), from the first load in the
+ * row; ran says whether Google's registry held it on some step (left out for captures that didn't record it).
+ * Containers the page asked for without the tool seeing a script added are rows too (see unseenContainers).
  */
 export function containerRows(runs) {
   const rows = new Map();
   for (const run of runs) {
-    for (const l of loadSources(run)) {
+    const ran = Array.isArray(run.containersRunning) ? new Set(run.containersRunning.map((c) => c.id)) : null;
+    for (const l of [...loadSources(run), ...unseenContainers(run)]) {
       const k = [l.id, l.kind, l.by ?? "", l.host, l.layer, l.environment ?? "", l.frame?.origin ?? ""].join("|");
       const row = rows.get(k) ?? {
         id: l.id, script: l.script, layer: l.layer, served: l.served, host: l.host,
@@ -165,12 +171,63 @@ export function containerRows(runs) {
       };
       if (l.page) row.pages.add(l.page);
       row.journeys.add(`${run.journeyId} (${run.viewport})`);
+      // Whether it ran (Google's registry held it) in any run that recorded the registry; unknown for older captures.
+      if (ran) row.ran = Boolean(row.ran) || ran.has(l.id);
       rows.set(k, row);
     }
   }
   return [...rows.values()].map((r) => ({ ...r, pages: [...r.pages].sort(), journeys: [...r.journeys] }));
 }
 
+/**
+ * Containers a run met without seeing a script added for them: a script the page requested or preloaded, or an ID
+ * that ran (Google's registry held it), with no load recorded. kind "preload": only a <link rel="preload"> asked for
+ * it, which downloads a script without running it; "unseen": something added it in a way the tool couldn't follow,
+ * as when a consent platform's auto-blocking replaces the browser's own functions. One per container and host.
+ */
+export function unseenContainers(run) {
+  const loads = run.containerLoads ?? [];
+  const loaded = (id, host) => loads.some((l) => l.id === id && (!host || l.host === host));
+  const preloads = run.containerPreloads ?? [];
+  const out = new Map();
+  // The page a step was on: the preload's own, else the step's (see pagePath in browser.js).
+  const pageAt = (step, page) => page ?? run.steps?.[step]?.pagePath ?? undefined;
+  const add = (id, host, kind, step, facts = {}, page) => {
+    const k = `${id}|${host ?? ""}`;
+    if (out.has(k) || loaded(id, host)) return;
+    const at = pageAt(step, page);
+    out.set(k, {
+      id, script: id.startsWith("GTM-") ? "gtm" : "gtag", layer: null,
+      ...(host ? { host, served: /(^|\.)googletagmanager\.com$/.test(host) ? "google" : "site" } : {}),
+      kind, step, ...(at ? { page: at } : {}), ...facts,
+    });
+  };
+  for (const sc of run.containerScripts ?? []) {
+    const pre = preloads.find((p) => p.id === sc.id && p.host === sc.host);
+    add(sc.id, sc.host, pre ? "preload" : "unseen", pre?.step ?? sc.step, scriptFacts(sc), pre?.page);
+  }
+  for (const p of preloads) add(p.id, p.host, "preload", p.step, {}, p.page);
+  for (const c of run.containersRunning ?? []) {
+    if (!loaded(c.id) && ![...out.values()].some((x) => x.id === c.id)) add(c.id, null, "unseen", c.step);
+  }
+  return [...out.values()];
+}
+
+/**
+ * GTM containers a run downloaded or asked for that never ran: Google's registry never held them on any step. Only
+ * GTM containers, whose registry entry is certain; [] for captures that didn't record the registry.
+ */
+export function containersNotRun(run) {
+  if (!Array.isArray(run.containersRunning)) return [];
+  const ran = new Set(run.containersRunning.map((c) => c.id));
+  const seen = new Map();
+  for (const l of [...loadSources(run), ...unseenContainers(run)]) {
+    if (!l.id.startsWith("GTM-") || ran.has(l.id) || l.failed || l.frame?.party === "third" || seen.has(l.id)) continue;
+    seen.set(l.id, { id: l.id, kind: l.kind, step: l.step ?? 0 });
+  }
+  return [...seen.values()];
+}
+
 /** The containers loaded more than once into one page, as [{ id, loads }] with the loads in order. */
 export function duplicateLoads(run) {
   const byDoc = new Map();

package/src/help.js

@@ -13,6 +13,7 @@ Commands:
   run      Audit what a site actually sends, and compare it to a plan
   replay   Re-check saved sites offline, without AI
   mcp      Start the MCP server for Claude, ChatGPT and other chat apps
+  login    Log in to a site by hand once and save the session for runs to start from
   doctor   Check that Node, Chromium, an AI key and the data folder are ready
   history  Show how a site's saved runs trend: counts, open problems, flapping, journeys
 
@@ -41,6 +42,7 @@ Options:
   --events <names>     Only check these events, e.g. purchase,add_to_cart
   --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
   --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)
@@ -106,6 +108,23 @@ Advanced:
   --reports <dir>      Where finished audits write reports (default: ~/ai-tag-debugger-reports)
   --public-url <url>   The HTTPS address of your tunnel or host, so audits can link to reports`;
 
+const LOGIN = `Usage: aitd login --site <url> [--save <file>] [--allow-host <host>] [--data-dir <dir>]
+
+Open the site in a browser window, log in by hand (a CAPTCHA, a code sent to your phone or
+single sign-on are fine), then press Enter in the terminal: the logged-in session (cookies and
+storage) is saved to aitd/<domain>/session.json. Runs start from it with --session saved.
+The file holds a live login: keep it private, and save it again when the login expires.
+
+For journeys that can log in by themselves, set a test account instead:
+AITD_LOGIN_EMAIL (or AITD_LOGIN_USERNAME) and AITD_LOGIN_PASSWORD. The model sees only
+the placeholders {{login.email}} and {{login.password}}; the browser types the real values.
+
+Options:
+  --site <url>         The site to log in to (required)
+  --save <file>        Where to save the session (default: aitd/<domain>/session.json)
+  --allow-host <host>  Another host the login passes through, such as a single sign-on page (repeatable)
+  --data-dir <dir>     The folder plans and runs are saved in (default: aitd)`;
+
 const DOCTOR = `Usage: aitd doctor [--site <url>] [--data-dir <dir>]
 
 Check that this machine can run an audit: the Node version, Playwright's Chromium, whether
@@ -130,7 +149,7 @@ Options:
   --lang <code>        Language of the lines: ${Object.keys(LANGUAGES).join(" or ")}
   --data-dir <dir>     The folder plans and runs are saved in (default: aitd)`;
 
-const HELP = { run: RUN, plan: PLAN, replay: REPLAY, mcp: MCP, doctor: DOCTOR, history: HISTORY };
+const HELP = { run: RUN, plan: PLAN, replay: REPLAY, mcp: MCP, login: LOGIN, doctor: DOCTOR, history: HISTORY };
 
 /** Help text for a command, or the top-level help when the command is unknown or missing. */
 export function helpText(command) {

package/src/html/scope.js

@@ -202,7 +202,7 @@ function containersCard(ctx) {
   const rows = containerRows(runs);
   if (!rows.length) return null;
   const c = m.ui.containers;
-  const items = rows.map((r) => `<li>${code(r.id)}${plain(esc(c.script[r.script]))}<span>${esc(c.kinds[r.kind](r.by))}</span>${plain(`${esc(m.ui.layerCol)} ${code(r.layer)}`)}${plain(esc(r.served === "google" ? c.served.google : `${c.served.site} (${r.host})`))}${r.version ? plain(esc(c.version(r.version)), "mono") : ""}${r.bytes ? plain(esc(c.size(r.bytes)), "mono") : ""}${r.ms != null ? plain(esc(c.loadTime(r.ms))) : ""}${r.failed ? badge("broken", c.failed(r.failed)) : ""}${r.frame ? plain(esc(c.iframe(r.frame.origin, r.frame.party))) : ""}${r.environment ? badge("warning", c.environment(r.environment)) : ""}<span class="inv-n">${m.html.scope.pages(r.pages.length, bold(r.pages.length))}</span></li>`).join("");
+  const items = rows.map((r) => `<li>${code(r.id)}${plain(esc(c.script[r.script]))}<span>${esc(c.kinds[r.kind](r.by))}</span>${r.ran === false ? badge("broken", c.neverRan) : ""}${r.layer ? plain(`${esc(m.ui.layerCol)} ${code(r.layer)}`) : ""}${r.served ? plain(esc(r.served === "google" ? c.served.google : `${c.served.site} (${r.host})`)) : ""}${r.version ? plain(esc(c.version(r.version)), "mono") : ""}${r.bytes ? plain(esc(c.size(r.bytes)), "mono") : ""}${r.ms != null ? plain(esc(c.loadTime(r.ms))) : ""}${r.failed ? badge("broken", c.failed(r.failed)) : ""}${r.frame ? plain(esc(c.iframe(r.frame.origin, r.frame.party))) : ""}${r.environment ? badge("warning", c.environment(r.environment)) : ""}<span class="inv-n">${m.html.scope.pages(r.pages.length, bold(r.pages.length))}</span></li>`).join("");
   const ids = uniq(rows.map((r) => r.id));
   return `<li><details class="card inv" id="inv-containers"><summary><span class="t">${esc(m.ui.containersTitle)}</span>${plain(n(ids.length))}<span class="inv-m">${esc(ids.slice(0, 3).join(", "))}${ids.length > 3 ? " …" : ""}</span></summary><div class="body"><p class="xs muted">${esc(m.ui.containersIntro)}</p><ul class="inv-list">${items}</ul></div></details></li>`;
 }

package/src/i18n.js

@@ -244,6 +244,7 @@ const en = {
       size: (bytes) => `${(bytes / 1024).toFixed(1)} KB`,
       loadTime: (ms) => `loaded in ${ms} ms`,
       failed: (status) => (status === "failed" ? "failed to load" : `failed to load (HTTP ${status})`),
+      neverRan: "never ran",
       kinds: {
         html: () => "A script tag in the page's HTML",
         inline: () => "Inline code in the page (the snippet)",
@@ -254,6 +255,8 @@ const en = {
         config: (by) => `A gtag('config') command, loaded by ${by}`,
         send_to: (by) => `An event's send_to with no config, loaded by ${by}`,
         destination: (by) => `A destination of the Google tag ${by}`,
+        preload: () => "Only a preload hint in the page (<link rel=\"preload\">): downloaded, never added as a script",
+        unseen: () => "Not seen being added: a script on the page may have replaced the browser's own functions, as consent platforms that block scripts do",
       },
     },
     provider: "Provider",
@@ -385,6 +388,9 @@ const en = {
     widgetTracking: (origin, platforms) => `An embedded widget from ${origin} sent its own tracking: ${platforms.map((p) => `${label(p.platform)}${p.ids.length ? ` (${p.ids.join(", ")})` : ""} ${p.events.map(q).join(", ")}`).join("; ")}. It goes to accounts the site's own tags don't use, so it was left out of the plan, coverage and duplicate checks; the consent and personal data checks still include it.`,
     iframeContainer: (id, origin, parent) => `${id} runs in an iframe from ${origin} embedded in ${parent}. The iframe has its own dataLayer: events and consent commands pushed in the page never reach it, so it needs its own.`,
     containerFailed: (id, host, status) => `The ${id} script from ${host} ${status === "failed" ? "failed to load" : `was answered with HTTP ${status}`}, so none of its tags ran on that page.`,
+    userIdMissing: (n) => `After logging in with the test account, ${n} GA4 ${n === 1 ? "hit went" : "hits went"} out without a user ID (uid). GA4 can't tie the visit to the account, so reports by user and journeys across devices miss it.`,
+    containerNotRun: (id, kind) => `${id} ${kind === "preload" ? "was downloaded because of a preload hint in the page, but nothing added it as a script, and it" : "was loaded but"} never ran on any page of this run: Google's own registry never held it, so none of its tags fired.`,
+    containerHeld: (id, vendor) => `${id} never ran, which is expected while ${vendor} holds it back until the visitor consents. This run never consented, so its tags weren't checked.`,
     widgetEventsUnshared: (origin, names) => `An embedded widget from ${origin} pushed ${names.map(q).join(", ")} to its own dataLayer, but none of its hits to the site's accounts carried ${names.length === 1 ? "it" : "them"}. The page's tags can't read a widget's dataLayer, so ${names.length === 1 ? "this event reaches" : "these events reach"} only the widget's own tracking.`,
     iframeMessageUnhandled: (origin, name, party) => `${party === "site" ? "An iframe on the site" : "An embedded widget"} from ${origin} posted ${q(name)} to the page, but the page pushed nothing to its dataLayer and sent no hit in the 3 seconds after, nor ${q(name)} later. If it is a conversion, the page isn't relaying it to its tags.`,
     consentDefaultMissing: () => "No Google Consent Mode default command (gtag('consent', 'default', ...)) was found in the dataLayer.",
@@ -449,6 +455,9 @@ const en = {
     widget_tracking: "Nothing is wrong with the site's tracking: the widget's own hits were kept out of the plan checks so they can't pass for the site's.",
     iframe_container: "Tags in the iframe miss what the page pushes, so conversions completed in it can go untracked or be sent without the visitor's consent.",
     container_failed: "None of the container's tags ran: page views, conversions and consent signals it sends were all lost on that page.",
+    user_id_missing: "Logged-in visits can't be tied to their accounts in GA4, so user-level reports and cross-device journeys undercount them.",
+    container_not_run: "None of the container's tags fired: page views, conversions and remarketing were all lost wherever it never ran.",
+    container_held: "The container's tags weren't checked on this run, since it waited for a consent the run never gave.",
     widget_events_unshared: "Conversions completed in the widget, such as a booking, a payment or a form, can be missing from the site's analytics and ad accounts.",
     iframe_message_unhandled: "A conversion completed in the iframe, such as a form sent or a booking made, can go untracked although the iframe told the page about it.",
     campaign_params: "Campaign parameters survived the landing redirect and reached the hits, so paid clicks are credited to their campaigns.",
@@ -500,6 +509,9 @@ const en = {
     widget_tracking: "Nothing to fix for the plan. If the widget sets cookies or sends data before consent, the consent findings name it; ask its vendor how to hold it back.",
     iframe_container: "Push the events and the consent state inside the iframe as well (or pass them in with postMessage), or track the iframe's steps from the page.",
     container_failed: "Check the container ID and the address in the snippet; for a server container or the Google tag gateway, check that it serves gtm.js and gtag/js.",
+    user_id_missing: "Once the visitor is logged in, set user_id on the Google tag (the user_id field of the GA4 Google tag in GTM, or gtag('config', ID, { user_id })) to your own account ID, never an email.",
+    container_not_run: "Check that something actually adds the container's script, the snippet or the framework component that loads it (a preload alone runs nothing); look for script errors that stop the page's own code, and for a consent platform that never releases it.",
+    container_held: "Run the journey with consent accepted, or the consent scenarios, to check the container's tags.",
     widget_events_unshared: "If the site needs these events, have the widget send them to the site's accounts (most booking and form widgets take a GA4 or GTM ID), or pass them to the page with postMessage and push them to the page's dataLayer.",
     iframe_message_unhandled: "Add a message listener on the page that checks event.origin and pushes the event to the dataLayer, so a GTM trigger can fire on it; or have the iframe send the event to the site's accounts itself.",
     campaign_params: "Nothing to fix. Check the redirects again when the landing pages change.",
@@ -551,6 +563,9 @@ const en = {
     widget_tracking: "hygiene",
     iframe_container: "hygiene",
     container_failed: "money",
+    user_id_missing: "hygiene",
+    container_not_run: "money",
+    container_held: "hygiene",
     widget_events_unshared: "money",
     iframe_message_unhandled: "money",
     campaign_params: "money",
@@ -1113,6 +1128,7 @@ const tr = {
       size: (bytes) => `${(bytes / 1024).toFixed(1).replace(".", ",")} KB`,
       loadTime: (ms) => `${ms} ms'de yüklendi`,
       failed: (status) => (status === "failed" ? "yüklenemedi" : `yüklenemedi (HTTP ${status})`),
+      neverRan: "hiç çalışmadı",
       kinds: {
         html: () => "Sayfanın HTML'indeki bir script etiketi",
         inline: () => "Sayfadaki satır içi kod (snippet)",
@@ -1123,6 +1139,8 @@ const tr = {
         config: (by) => `Bir gtag('config') komutu, ${by} yükledi`,
         send_to: (by) => `config olmadan bir olayın send_to değeri, ${by} yükledi`,
         destination: (by) => `${by} Google etiketinin bir hedefi`,
+        preload: () => "Sayfada yalnızca bir ön yükleme ipucu (<link rel=\"preload\">): indirildi, hiç betik olarak eklenmedi",
+        unseen: () => "Eklendiği görülmedi: sayfadaki bir betik tarayıcının kendi işlevlerini değiştirmiş olabilir; betikleri engelleyen onay platformlarının yaptığı gibi",
       },
     },
     provider: "Sağlayıcı",
@@ -1250,6 +1268,9 @@ const tr = {
     widgetTracking: (origin, platforms) => `${origin} kaynaklı gömülü bir widget kendi izlemesini gönderdi: ${platforms.map((p) => `${label(p.platform)}${p.ids.length ? ` (${p.ids.join(", ")})` : ""} ${p.events.map(q).join(", ")}`).join("; ")}. Bunlar sitenin kendi etiketlerinin kullanmadığı hesaplara gidiyor; bu yüzden plan, kapsam ve tekrar kontrollerinin dışında tutuldu, onay ve kişisel veri kontrolleri ise onları yine içeriyor.`,
     iframeContainer: (id, origin, parent) => `${id}, ${parent} içine gömülü ${origin} kaynaklı bir iframe içinde çalışıyor. iframe'in kendi dataLayer'ı var: sayfada gönderilen olaylar ve onay komutları ona hiç ulaşmaz, bu yüzden kendi olaylarına ve onayına ihtiyacı var.`,
     containerFailed: (id, host, status) => `${host} adresinden gelen ${id} betiği ${status === "failed" ? "yüklenemedi" : `HTTP ${status} ile yanıtlandı`}; bu yüzden o sayfada etiketlerinin hiçbiri çalışmadı.`,
+    userIdMissing: (n) => `Test hesabıyla giriş yapıldıktan sonra ${n} GA4 isteği kullanıcı kimliği (uid) olmadan gönderildi. GA4 ziyareti hesaba bağlayamıyor; bu yüzden kullanıcıya göre raporlar ve cihazlar arası yolculuklar onu kaçırıyor.`,
+    containerNotRun: (id, kind) => `${id} ${kind === "preload" ? "sayfadaki bir ön yükleme ipucu yüzünden indirildi, ama hiçbir şey onu betik olarak eklemedi ve" : "yüklendi ama"} bu çalıştırmanın hiçbir sayfasında çalışmadı: Google'ın kendi kaydı onu hiç tutmadı, bu yüzden etiketlerinin hiçbiri çalışmadı.`,
+    containerHeld: (id, vendor) => `${id} hiç çalışmadı; ${vendor} onu ziyaretçi onay verene kadar beklettiği sürece bu beklenen bir durum. Bu çalıştırmada onay hiç verilmedi, bu yüzden etiketleri kontrol edilmedi.`,
     widgetEventsUnshared: (origin, names) => `${origin} kaynaklı gömülü bir widget kendi dataLayer'ına ${names.map(q).join(", ")} gönderdi, ancak sitenin hesaplarına giden isteklerinin hiçbiri ${names.length === 1 ? "onu" : "onları"} taşımadı. Sayfanın etiketleri bir widget'ın dataLayer'ını okuyamaz; bu yüzden ${names.length === 1 ? "bu olay" : "bu olaylar"} yalnızca widget'ın kendi izlemesine ulaşıyor.`,
     iframeMessageUnhandled: (origin, name, party) => `${origin} kaynaklı ${party === "site" ? "sitedeki bir iframe" : "gömülü bir widget"} sayfaya ${q(name)} gönderdi, ancak sayfa ardından 3 saniye içinde dataLayer'a hiçbir şey göndermedi ve istek yollamadı, sonradan ${q(name)} da göndermedi. Bu bir dönüşümse sayfa onu etiketlerine iletmiyor.`,
     consentDefaultMissing: () => "dataLayer'da Google Consent Mode varsayılan komutu (gtag('consent', 'default', ...)) bulunamadı.",
@@ -1313,6 +1334,9 @@ const tr = {
     widget_tracking: "Sitenin izlemesinde bir sorun yok: widget'ın kendi istekleri sitenin isteklerinin yerine geçmesin diye plan kontrollerinin dışında tutuldu.",
     iframe_container: "iframe içindeki etiketler sayfanın gönderdiklerini görmez; içinde tamamlanan dönüşümler izlenmeyebilir ya da ziyaretçinin onayı olmadan gönderilebilir.",
     container_failed: "Container'ın etiketlerinin hiçbiri çalışmadı: gönderdiği sayfa görüntülemeleri, dönüşümler ve onay sinyalleri o sayfada kayboldu.",
+    user_id_missing: "Giriş yapılmış ziyaretler GA4'te hesaplarına bağlanamıyor; kullanıcı düzeyindeki raporlar ve cihazlar arası yolculuklar onları eksik sayıyor.",
+    container_not_run: "Container'ın etiketlerinin hiçbiri çalışmadı: hiç çalışmadığı her yerde sayfa görüntülemeleri, dönüşümler ve yeniden pazarlama kayboldu.",
+    container_held: "Container onay beklediği ve bu çalıştırma onay vermediği için etiketleri kontrol edilmedi.",
     widget_events_unshared: "Widget içinde tamamlanan dönüşümler, örneğin bir rezervasyon, ödeme ya da form, sitenin analitik ve reklam hesaplarında eksik kalabilir.",
     iframe_message_unhandled: "iframe içinde tamamlanan bir dönüşüm (gönderilen bir form, yapılan bir rezervasyon), iframe sayfaya bildirdiği hâlde izlenmeyebilir.",
     campaign_params: "Kampanya parametreleri açılış yönlendirmesinden geçip isteklere ulaştı; ücretli tıklamalar kendi kampanyalarına yazılıyor.",
@@ -1362,6 +1386,9 @@ const tr = {
     widget_tracking: "Plan için düzeltilecek bir şey yok. Widget onaydan önce çerez yazıyor ya da veri gönderiyorsa onay bulguları onu adlandırır; nasıl durdurulacağını sağlayıcısına sorun.",
     iframe_container: "Olayları ve onay durumunu iframe içinde de gönderin (ya da postMessage ile iletin) veya iframe'deki adımları sayfadan izleyin.",
     container_failed: "Snippet'teki container kimliğini ve adresi kontrol edin; sunucu container'ı ya da Google etiket ağ geçidi için gtm.js ve gtag/js sunduğunu kontrol edin.",
+    user_id_missing: "Ziyaretçi giriş yaptıktan sonra Google etiketinde user_id'yi kendi hesap kimliğinize ayarlayın (GTM'deki GA4 Google etiketinin user_id alanı ya da gtag('config', ID, { user_id })); asla bir e-posta kullanmayın.",
+    container_not_run: "Container betiğini gerçekten bir şeyin eklediğini kontrol edin: snippet ya da onu yükleyen çatı bileşeni (yalnızca ön yükleme hiçbir şeyi çalıştırmaz); sayfanın kendi kodunu durduran betik hatalarına ve onu hiç serbest bırakmayan bir onay platformuna bakın.",
+    container_held: "Container'ın etiketlerini kontrol etmek için yolculuğu onay kabul edilmiş olarak ya da onay senaryolarıyla çalıştırın.",
     widget_events_unshared: "Site bu olaylara ihtiyaç duyuyorsa widget'ın onları sitenin hesaplarına göndermesini sağlayın (çoğu rezervasyon ve form widget'ı bir GA4 ya da GTM kimliği kabul eder) ya da onları postMessage ile sayfaya iletip sayfanın dataLayer'ına gönderin.",
     iframe_message_unhandled: "Sayfaya event.origin'i kontrol eden ve olayı dataLayer'a gönderen bir message dinleyicisi ekleyin, böylece bir GTM tetikleyicisi onunla çalışabilir; ya da iframe'in olayı sitenin hesaplarına kendisi göndermesini sağlayın.",
     campaign_params: "Düzeltilecek bir şey yok. Açılış sayfaları değiştiğinde yönlendirmeleri yeniden kontrol edin.",
@@ -1412,6 +1439,9 @@ const tr = {
     widget_tracking: "hygiene",
     iframe_container: "hygiene",
     container_failed: "money",
+    user_id_missing: "hygiene",
+    container_not_run: "money",
+    container_held: "hygiene",
     widget_events_unshared: "money",
     iframe_message_unhandled: "money",
     campaign_params: "money",

package/src/journeys.js

@@ -39,6 +39,12 @@ export const JOURNEY_PRESETS = {
       { platform: "meta", name: "Lead" },
     ],
   },
+  login: {
+    goal: "Accept cookies, open the login or sign-in page, and log in with the test account: fill {{login.email}} (or {{login.username}} where the site asks for a username) and {{login.password}}, then submit. Stop when the site shows you are logged in.",
+    events: [
+      { platform: "ga4", name: "login" },
+    ],
+  },
   search: {
     goal: "Accept cookies, use the site search to search for a common product or topic, and open the first result.",
     events: [
@@ -52,7 +58,7 @@ export const JOURNEY_PRESETS = {
   },
 };
 
-const ALIASES = { checkout: "purchase", order: "purchase", cart: "add_to_cart", signup: "sign_up", decline: "decline_cookies", reject: "decline_cookies", reject_cookies: "decline_cookies", consent: "decline_cookies", register: "sign_up", registration: "sign_up", contact: "lead", form: "lead" };
+const ALIASES = { signin: "login", sign_in: "login", log_in: "login", checkout: "purchase", order: "purchase", cart: "add_to_cart", signup: "sign_up", decline: "decline_cookies", reject: "decline_cookies", reject_cookies: "decline_cookies", consent: "decline_cookies", register: "sign_up", registration: "sign_up", contact: "lead", form: "lead" };
 
 /** The preset for a name like "purchase" or "signup", or null. */
 export function presetFor(name) {
@@ -168,6 +174,7 @@ const PRESET_BY_EVENT = [
   ["purchase", ["purchase", "add_payment_info", "add_shipping_info", "begin_checkout"]],
   ["add_to_cart", ["add_to_cart", "view_cart"]],
   ["sign_up", ["sign_up"]],
+  ["login", ["login"]],
   ["lead", ["generate_lead"]],
   ["search", ["search", "view_search_results"]],
 ];

package/src/login.js

@@ -0,0 +1,91 @@
+// A test account for journeys that log in. The email (or username) and password come from environment variables on
+// the computer running the tool; the model only ever sees placeholders such as {{login.password}}, the browser fills
+// in the real values (on the audited site's pages only, see AuditSession.perform), and every text the tool records
+// or shows has them turned back into their placeholders.
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { domainOf } from "./workspace.js";
+
+export const LOGIN_ENV = { email: "AITD_LOGIN_EMAIL", username: "AITD_LOGIN_USERNAME", password: "AITD_LOGIN_PASSWORD" };
+
+const PLACEHOLDER = /\{\{\s*login\.(email|username|password)\s*\}\}/g;
+
+/**
+ * The test account the environment sets, as { email, username, password }, or null when none is set. username is
+ * AITD_LOGIN_USERNAME, else the email, for sites that ask for a username; email is the same the other way round.
+ */
+export function loginFromEnv(env = process.env) {
+  const email = env[LOGIN_ENV.email]?.trim() || "";
+  const username = env[LOGIN_ENV.username]?.trim() || "";
+  const password = env[LOGIN_ENV.password] ?? "";
+  if (!email && !username && !password) return null;
+  return { email: email || username, username: username || email, password };
+}
+
+/** Whether a value asks for the test account: it holds {{login.email}}, {{login.username}} or {{login.password}}. */
+export const hasLoginPlaceholder = (value) => typeof value === "string" && new RegExp(PLACEHOLDER.source).test(value);
+
+/**
+ * The value with its placeholders replaced by the test account's. Throws an error with code NO_LOGIN, naming the
+ * environment variables to set, when a placeholder asks for something the environment doesn't hold.
+ */
+export function fillLoginValue(value, login) {
+  return String(value).replace(PLACEHOLDER, (_, field) => {
+    const v = login?.[field];
+    if (!v) {
+      const name = field === "password" ? LOGIN_ENV.password : `${LOGIN_ENV.email} (or ${LOGIN_ENV.username})`;
+      const err = new Error(`No test account is set up for {{login.${field}}}: set ${name} on the computer running ai-tag-debugger. Without one, stop and report that the journey needs a login.`);
+      err.code = "NO_LOGIN";
+      throw err;
+    }
+    return v;
+  });
+}
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * A function that turns the test account's values back into their placeholders wherever they appear in a text, as
+ * typed or URL-encoded. Values shorter than 3 characters are left alone, since they would match ordinary text.
+ * Identity when there is no test account.
+ */
+export function loginScrubber(login) {
+  if (!login) return (text) => text;
+  const pairs = [];
+  const taken = new Set();
+  // The password first: an email inside a password must not leave the rest of the password behind. A username that is
+  // the email (the default) reads as {{login.email}}.
+  for (const [field, value] of [["password", login.password], ["email", login.email], ["username", login.username]]) {
+    if (!value || value.length < 3 || taken.has(value)) continue;
+    taken.add(value);
+    for (const form of new Set([value, encodeURIComponent(value), encodeURIComponent(value).replace(/%20/g, "+")])) pairs.push([form, `{{login.${field}}}`]);
+  }
+  if (!pairs.length) return (text) => text;
+  const re = new RegExp(pairs.map(([v]) => escape(v)).sort((a, b) => b.length - a.length).join("|"), "g");
+  const to = new Map(pairs);
+  return (text) => (typeof text === "string" && text ? text.replace(re, (m) => to.get(m) ?? m) : text);
+}
+
+/** A copy of a value with every string in it scrubbed: for hits' parameters, dataLayer pushes and the like. */
+export function scrubDeep(value, scrub) {
+  if (typeof value === "string") return scrub(value);
+  if (Array.isArray(value)) return value.map((v) => scrubDeep(v, scrub));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, scrubDeep(v, scrub)]));
+  return value;
+}
+
+/** Where `aitd login` saves a site's logged-in session by default: aitd/<domain>/session.json, a gitignored folder. */
+export function sessionFileFor(site, dataDir) {
+  return path.join(dataDir, domainOf(site), "session.json");
+}
+
+/**
+ * The session file a run should start from: "saved" for the one `aitd login` saved for the site, else a path.
+ * Throws when the file doesn't exist, with the command that saves one.
+ */
+export function resolveSessionFile(value, { site, dataDir }) {
+  const file = value === "saved" ? sessionFileFor(site, dataDir) : path.resolve(String(value));
+  if (!existsSync(file)) throw new Error(`No saved login session at ${file}. Save one with: aitd login --site ${site}`);
+  return file;
+}

package/src/mcp.js

@@ -33,7 +33,8 @@ import { decodeGcd, DEFAULT_PROVIDERS, googleConsent, isCollectionEndpoint, pars
 import { hitParams } from "./hit-params.js";
 import { CAMPAIGN_PARAMS, campaignParamsIn, withCampaignParams } from "./campaign.js";
 import { cmpFacts } from "./cmp.js";
-import { containerRows, loadSources } from "./containers.js";
+import { resolveSessionFile } from "./login.js";
+import { containerRows, containersNotRun, loadSources, unseenContainers } from "./containers.js";
 import { isEventMessage, isWidgetHit, messageOutcomes, pushedEvent, siteIds, splitRun, widgetSummaries } from "./frames.js";
 import { consentMatrixMarkdown, consentTable, runConsentScenarios } from "./consent.js";
 import { expectEvents, filterFindings, JOURNEY_PRESETS, onlyEvents, presetFor, withPresetEvents } from "./journeys.js";
@@ -244,7 +245,7 @@ export function hitDetail(audit, step, index) {
 function containerJson(l) {
   return {
     id: l.id, source: l.kind, ...(l.by ? { by: l.by } : {}),
-    ...(l.layer !== "dataLayer" ? { data_layer: l.layer } : {}),
+    ...(l.layer && l.layer !== "dataLayer" ? { data_layer: l.layer } : {}),
     ...(l.served === "site" ? { served_from: l.host } : {}),
     ...(l.environment ? { gtm_environment: l.environment } : {}),
     ...(l.frame ? { iframe: { origin: l.frame.origin, party: l.frame.party } } : {}),
@@ -253,6 +254,7 @@ function containerJson(l) {
     ...(l.transferBytes ? { transfer_bytes: l.transferBytes } : {}),
     ...(l.ms != null ? { load_ms: l.ms } : {}),
     ...(l.failed ? { failed: l.failed } : {}),
+    ...(typeof l.ran === "boolean" ? { ran: l.ran } : {}),
     ...(l.pages ? { pages: l.pages } : {}),
   };
 }
@@ -265,7 +267,7 @@ export function containerLines(runs) {
   return [
     "Google containers (how each reached the page):",
     ...rows.map((r) => {
-      const extra = [scriptCell(c, r), r.layer !== "dataLayer" && `dataLayer ${r.layer}`, r.served === "site" && `served from ${r.host}`, r.environment && c.environment(r.environment), r.frame && c.iframe(r.frame.origin, r.frame.party), `${r.pages.length} ${r.pages.length === 1 ? "page" : "pages"}`].filter(Boolean);
+      const extra = [scriptCell(c, r), r.layer && r.layer !== "dataLayer" && `dataLayer ${r.layer}`, r.served === "site" && `served from ${r.host}`, r.environment && c.environment(r.environment), r.frame && c.iframe(r.frame.origin, r.frame.party), `${r.pages.length} ${r.pages.length === 1 ? "page" : "pages"}`].filter(Boolean);
       return `  ${r.id} (${c.script[r.script]}): ${c.kinds[r.kind](r.by)}; ${extra.join(", ")}`;
     }),
   ];
@@ -440,10 +442,14 @@ 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}`),
+        session: z
+          .enum(["saved"])
+          .optional()
+          .describe("Start logged in, from the session saved for this site with `aitd login --site <url>` on the computer running this server. For sites whose login needs a person (a CAPTCHA or a code). Local servers only."),
         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 }) => {
+    async ({ site, journey, viewport, allowed_hosts, providers, campaign = true, live = false, session: savedSession }) => {
       let url;
       try {
         url = new URL(site);
@@ -460,7 +466,10 @@ export function buildServer(opts) {
       let session;
       try {
         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.");
-        session = new AuditSession({ viewport: viewport ?? "desktop", site: url.href, allowedHosts: allowed_hosts, providers, blockPrivate: opts.blockPrivate, blockHits: !live });
+        // 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.");
+        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 });
       } catch (err) {
         return fail(err.message);
       }
@@ -482,7 +491,8 @@ export function buildServer(opts) {
       const sent = campaignParamsIn(start);
       const opened = Object.keys(sent).length ? `Opened like an ad click with ${Object.entries(sent).map(([k, v]) => `${k}=${v}`).join(", ")}; finish_audit checks that they survive redirects and reach the hits.\n` : "";
       const liveLine = live ? `${LIVE_NOTE}\n` : "";
-      return text(`audit_id: ${id}\n${liveLine}${opened}${goal}\n${page}\n\n${stepCapture(audit, session.currentStep)}`);
+      const accountLine = `${session.login ? "A test account is set up: to log in, fill {{login.email}} (or {{login.username}}) and {{login.password}}, written exactly like that; the browser types the real values." : "No test account is set up on this computer (AITD_LOGIN_EMAIL and AITD_LOGIN_PASSWORD), so a journey that needs a login stops at it."}${savedSession ? " The browser started from the saved login session." : ""}\n`;
+      return text(`audit_id: ${id}\n${liveLine}${accountLine}${opened}${goal}\n${page}\n\n${stepCapture(audit, session.currentStep)}`);
     },
   );
 
@@ -575,10 +585,20 @@ export function buildServer(opts) {
     },
     async ({ audit_id }) => {
       const { session } = getAudit(audit_id);
-      const loads = loadSources({ containerLoads: session.containerLoads ?? [], containerScripts: session.containerScripts, dataLayerLog: session.dataLayerLog });
-      if (!loads.length) return text("No GTM container or Google tag script has loaded on this audit's pages yet.");
+      const run = {
+        containerLoads: session.containerLoads ?? [], containerScripts: session.containerScripts, dataLayerLog: session.dataLayerLog,
+        containerPreloads: [...(session.containerPreloads?.values() ?? [])],
+        containersRunning: [...(session.containersRunning ?? [])].map(([id, step]) => ({ id, step })),
+      };
+      const loads = loadSources(run);
+      const unseen = unseenContainers(run);
+      const notRun = containersNotRun(run);
+      if (!loads.length && !unseen.length) return text("No GTM container or Google tag script has loaded on this audit's pages yet.");
+      const c = messages("en").ui.containers;
       const lines = loads.map((l) => `Step ${l.step} ("${session.steps[l.step]?.label ?? ""}"), ${l.page ?? "?"}:\n${describeLoad(l)}`);
-      return text(`${loads.length} container ${loads.length === 1 ? "load" : "loads"}:\n${lines.join("\n")}\n\nAs JSON: ${JSON.stringify(loads.map((l) => ({ step: l.step, page: l.page, ...containerJson(l) })))}`);
+      if (unseen.length) lines.push("Asked for without a script being seen added:", ...unseen.map((u) => `  ${u.id} (${c.script[u.script]}), step ${u.step}: ${c.kinds[u.kind]()}`));
+      if (notRun.length) lines.push(`Never ran so far (Google's registry never held ${notRun.length === 1 ? "it" : "them"}): ${notRun.map((x) => x.id).join(", ")}. If a consent platform holds GTM back, accept consent to see it run.`);
+      return text(`${loads.length} container ${loads.length === 1 ? "load" : "loads"}:\n${lines.join("\n")}\n\nAs JSON: ${JSON.stringify([...loads, ...unseen].map((l) => ({ step: l.step, page: l.page, ...containerJson(l), ...(l.id.startsWith("GTM-") ? { ran: run.containersRunning.some((r) => r.id === l.id) } : {}) })))}`);
     },
   );