@analitikisler/ai-tag-debugger 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.8.2 (2026-10-15)
+
+- A journey that fails with an error, such as the AI provider's API refusing a request or the browser crashing, no longer ends the whole audit. That journey is marked unfinished with the error as its note, what it captured until then is kept, the other journeys still run, and the report is written. This applies to the CLI and to `run_audit` over MCP.
+- A Consent Mode default pushed after the first Google hit is now reported as late (`consent_default_late`) when both happen on the same step, such as the start page. The check used to compare only step numbers, so it missed this. Only Google hits count, since Consent Mode only governs Google tags.
+- An unknown viewport, given with `--viewport` or in the config's `viewports`, now stops the audit at once with a message listing the allowed values (desktop, mobile). Before, it failed only when the browser started for that journey, after the model was set up and earlier journeys had run.
+- `ai-tag-debugger --version` (or `aitd -v`) prints the installed version.
+- New short command `aitd`, an alias for `ai-tag-debugger` installed alongside it.
+- For contributors: `npm run setup` checks the Node version, installs the dependencies and Chromium, and says whether an AI provider key is set. A dev container (`.devcontainer/devcontainer.json`) runs it, so VS Code and Codespaces open the repository ready to run.
+
+## 0.8.1 (2026-10-15)
+
+- A run with no AI provider key set now stops at once with a message naming the keys to set and the `--scripted --no-ai` option, instead of starting the browser and failing at the first step with the SDK's "Could not resolve authentication method".
+- Over MCP, `run_audit` with `scripted: false` and no key returns an error that tells the chat app what to do next: call it again with `scripted: true`, or browse with `start_audit`. It doesn't mention CLI flags.
+- The README points to `ai-tag-debugger --help` for the full list of commands and options.
+- `npm run demo` replays the demo shop with no AI model (`--no-ai`), so it works without an API key.
+
 ## 0.8.0 (2026-10-14)
 
 - The browser installs itself the first time an audit starts, so connecting the MCP server no longer needs a separate `playwright install` step. Progress goes to stderr.

package/README.md

@@ -110,8 +110,12 @@ export ANTHROPIC_API_KEY=...                # or OPENAI_API_KEY, or GEMINI_API_K
 ai-tag-debugger run --site https://staging.yourshop.com --journey add_to_cart --headed
 ```
 
+The global install also adds `aitd`, a short alias: `aitd run --site … --journey add_to_cart` does the same.
+
 Or run it without installing: `npx -y @analitikisler/ai-tag-debugger run --site … --journey add_to_cart`.
 
+Run `ai-tag-debugger --help` to see every command and option, such as `--providers`, `--scripted` and `--no-ai`.
+
 ### Try the demo shop (from source)
 
 The repository includes a demo shop with three deliberate tracking bugs:
@@ -250,6 +254,8 @@ ai-tag-debugger mcp [--http] [--port <n>] [--host <addr>] [--token <secret>] [--
                 [--allow-private-network]
 ```
 
+`aitd` is a short alias for `ai-tag-debugger` and takes the same commands and options.
+
 The exit code is `1` when findings reach `--fail-on` (default `broken`), so it can gate a deploy. See [`examples/github-actions/ai-tag-debugger.yml`](examples/github-actions/ai-tag-debugger.yml) for running it after every deployment.
 
 Output:
@@ -356,9 +362,12 @@ A hosted server, so you don't need a tunnel, is part of the [Analitik İşler](h
 ## Development
 
 ```bash
-npm test   # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
+npm run setup   # checks Node, installs the dependencies and Chromium, says whether an AI provider key is set
+npm test        # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
 ```
 
+The repository also has a dev container (`.devcontainer/devcontainer.json`). Open it in VS Code with the Dev Containers extension, or in GitHub Codespaces, and it runs `npm run setup` for you, Chromium's system libraries included. To use an AI model there, add your key as a Codespaces secret or export it in the container's terminal.
+
 The end-to-end tests use fake model clients, so they run without an API key.
 
 ## Hosted version

package/README.tr.md

@@ -110,8 +110,12 @@ export ANTHROPIC_API_KEY=...                # or OPENAI_API_KEY, or GEMINI_API_K
 ai-tag-debugger run --site https://staging.yourshop.com --journey add_to_cart --headed
 ```
 
+Global kurulum kısa bir takma ad olan `aitd` komutunu da ekler: `aitd run --site … --journey add_to_cart` aynı işi yapar.
+
 Ya da kurmadan çalıştırın: `npx -y @analitikisler/ai-tag-debugger run --site … --journey add_to_cart`.
 
+Tüm komutları ve seçenekleri (`--providers`, `--scripted`, `--no-ai` gibi) görmek için `ai-tag-debugger --help` çalıştırın.
+
 ### Demo mağazayı deneyin (kaynak koddan)
 
 Depoda, bilerek bırakılmış üç ölçümleme hatası olan bir demo mağaza var:
@@ -250,6 +254,8 @@ ai-tag-debugger mcp [--http] [--port <n>] [--host <addr>] [--token <secret>] [--
                 [--allow-private-network]
 ```
 
+`aitd`, `ai-tag-debugger` için kısa bir takma addır ve aynı komut ve seçenekleri alır.
+
 Bulgular `--fail-on` seviyesine (varsayılan `broken`) ulaştığında çıkış kodu `1` olur, böylece bir deploy'u durdurabilir. Her deploy sonrası çalıştırmak için [`examples/github-actions/ai-tag-debugger.yml`](examples/github-actions/ai-tag-debugger.yml) örneğine bakın.
 
 Çıktılar:
@@ -356,9 +362,12 @@ Tünele gerek kalmayan, hazır bir adresle barındırılan sunucu, [Analitik İ
 ## Geliştirme
 
 ```bash
-npm test   # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
+npm run setup   # checks Node, installs the dependencies and Chromium, says whether an AI provider key is set
+npm test        # parsers, checks, each AI provider and the MCP server, end to end against the demo shop
 ```
 
+Depoda bir dev container (`.devcontainer/devcontainer.json`) da var. Depoyu VS Code'da Dev Containers eklentisiyle ya da GitHub Codespaces'te açtığınızda `npm run setup` sizin için çalışır ve Chromium'un sistem kütüphanelerini de kurar. Orada bir yapay zekâ modeli kullanmak için anahtarınızı Codespaces secret olarak ekleyin ya da container'ın terminalinde export edin.
+
 Uçtan uca testler sahte model istemcileri kullanır, bu yüzden API anahtarı olmadan çalışır.
 
 ## Barındırılan sürüm

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@analitikisler/ai-tag-debugger",
   "mcpName": "io.github.analitikisler/ai-tag-debugger",
-  "version": "0.8.0",
+  "version": "0.8.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"
+    "ai-tag-debugger": "src/cli.js",
+    "aitd": "src/cli.js"
   },
   "files": [
     "src",
@@ -14,9 +15,10 @@
     "CHANGELOG.md"
   ],
   "scripts": {
+    "setup": "node scripts/setup.js",
     "test": "node --test test/*.test.js",
     "demo:serve": "node examples/serve.js",
-    "demo": "node src/cli.js run --config examples/demo.config.json --scripted --out reports/demo"
+    "demo": "node src/cli.js run --config examples/demo.config.json --scripted --no-ai --out reports/demo"
   },
   "engines": {
     "node": ">=20"

package/src/agent.js

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

package/src/audit.js

@@ -2,7 +2,8 @@
 // Shared by the CLI and the MCP server's run_audit tool.
 import { readFile, mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { runJourney } from "./agent.js";
+import { failedRun, runJourney } from "./agent.js";
+import { VIEWPORTS } from "./browser.js";
 import { checkRun, groupFindings, summarize } from "./checks.js";
 import { explainFindings, renderCsv, renderHtml, renderMarkdown } from "./report.js";
 import { LANGUAGES, messages } from "./i18n.js";
@@ -70,6 +71,10 @@ export async function runAudit(opts) {
   const { journeys, plan } = planRun({ config, plan: opts.plan, picks: opts.journeys, goals: opts.goals, events });
   config = { ...config, providers: resolveProviders(opts.providers ?? config.providers, plan) };
   const viewports = opts.viewports?.length ? opts.viewports : config.viewports ?? ["desktop"];
+  const allowed = Object.keys(VIEWPORTS).join(", ");
+  if (!Array.isArray(viewports)) throw new Error(`"viewports" must be a list, e.g. ["desktop", "mobile"]. Allowed values: ${allowed}.`);
+  const unknown = viewports.filter((v) => !Object.hasOwn(VIEWPORTS, v));
+  if (unknown.length) throw new Error(`Unknown viewport ${unknown.map((v) => `"${v}"`).join(", ")}. Use: ${allowed}.`);
   if (!journeys.length) throw new Error("No journeys to run. Pick one with --journey (e.g. purchase) or describe one with --goal.");
   if (opts.scripted) {
     const unscripted = journeys.filter((j) => !j.steps?.length && !j.incomplete).map((j) => j.id);
@@ -84,7 +89,9 @@ export async function runAudit(opts) {
   for (const journey of journeys) {
     for (const viewport of viewports) {
       log(`\n▶ ${journey.id} (${viewport})`);
-      const run = await runJourney(config, journey, viewport, { scripted: opts.scripted, provider, maxSteps: opts.maxSteps, headed: opts.headed, lang, log, saveSite: opts.saveSite, replaySite: opts.replaySite });
+      // runJourney keeps its own errors in the run. This catches the rest, such as a browser that won't close,
+      // so one journey can't cost the report of the others.
+      const run = await runJourney(config, journey, viewport, { scripted: opts.scripted, provider, maxSteps: opts.maxSteps, headed: opts.headed, lang, log, saveSite: opts.saveSite, replaySite: opts.replaySite }).catch((err) => failedRun(journey, viewport, err, config.providers));
       log(`  ${run.completed ? "✓" : "✗"} ${run.note} · ${run.hits.length} tracking hits captured`);
       runs.push(run);
     }

package/src/checks.js

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

package/src/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { loadConfig, runAudit } from "./audit.js";
@@ -8,6 +9,8 @@ import { JOURNEY_PRESETS } from "./journeys.js";
 import { PROVIDERS as TRACKING_PROVIDERS, DEFAULT_PROVIDERS } from "./parsers.js";
 import { replaySavedSite } from "./replay.js";
 
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
 const USAGE = `ai-tag-debugger: an open-source AI agent that QA-tests your analytics and ad tracking.
 
 Usage:
@@ -61,6 +64,9 @@ MCP options:
   --public-url <url>   The HTTPS address your tunnel or host gives this server, so audits can link to their reports.
 
   -h, --help           Show this help.
+  -v, --version        Print the version.
+
+Short alias: aitd (aitd run ... is the same as ai-tag-debugger run ...).
 
 API keys: set one of ${Object.values(PROVIDERS).map((p) => p.env).join(", ")}.
 Any OpenAI-compatible API: --provider openai-compatible --base-url <url> --model <id>, with the key in OPENAI_COMPATIBLE_API_KEY.`;
@@ -99,9 +105,14 @@ async function main() {
       "save-site": { type: "string" },
       update: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
     },
   });
   const command = positionals[0];
+  if (values.version) {
+    console.log(VERSION);
+    return;
+  }
 
   if (command === "mcp" && !values.help) {
     const { startMcp } = await import("./mcp.js");

package/src/mcp.js

@@ -293,7 +293,16 @@ export function buildServer(opts) {
       async ({ config: configFile, scripted, language, branding, providers }) => {
         const loaded = await loadConfig(configFile);
         const replay = scripted !== false;
-        const result = await runAudit({ ...loaded, scripted: replay, ai: !replay, lang: language, branding, providers, outDir: path.join(opts.reportsDir, new Date().toISOString().replace(/[:.]/g, "-")) });
+        let result;
+        try {
+          result = await runAudit({ ...loaded, scripted: replay, ai: !replay, lang: language, branding, providers, outDir: path.join(opts.reportsDir, new Date().toISOString().replace(/[:.]/g, "-")) });
+        } catch (err) {
+          // The CLI wording (--scripted --no-ai) means nothing to a chat app, so say it in this tool's terms.
+          if (err.code !== "NO_API_KEY") throw err;
+          return fail(
+            "No AI provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY) is set on the computer running this server, so scripted false can't browse with a model. Call run_audit again with scripted true (or leave it out) to replay the journeys' fixed steps, or browse the site yourself with start_audit, browser_action and finish_audit. Neither needs a key.",
+          );
+        }
         const m = messages(result.lang);
         const grouped = groupFindings(result.findings).filter((f) => f.severity !== "ok");
         return text(

package/src/providers.js

@@ -28,6 +28,12 @@ export function resolveProviderName(name, env = process.env) {
   return "anthropic";
 }
 
+const NO_API_KEY = `No AI provider key found. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY (or OPENAI_COMPATIBLE_BASE_URL for an OpenAI-compatible API), or pick one with --provider. To run without any AI model, replay the fixed steps with --scripted --no-ai.`;
+
+function hasApiKey(env) {
+  return Boolean(env.OPENAI_COMPATIBLE_BASE_URL || env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN || env.OPENAI_API_KEY || env.GEMINI_API_KEY || env.GOOGLE_API_KEY);
+}
+
 /**
  * @param {{ name?: string, model?: string, baseUrl?: string, client?: any }} opts
  *   baseUrl: for openai-compatible, e.g. https://api.deepseek.com or http://localhost:11434/v1.
@@ -36,6 +42,10 @@ export function resolveProviderName(name, env = process.env) {
 export async function createProvider(opts = {}, env = process.env) {
   // A bare client (tests, embedding) is an Anthropic client unless named otherwise.
   const name = opts.client && !opts.name ? "anthropic" : opts.baseUrl && !opts.name ? "openai-compatible" : resolveProviderName(opts.name, env);
+  // With no provider named and no key set, the SDK would only fail at the first step with an
+  // unclear auth error, after the browser has started. A named provider skips this check, since
+  // its SDK may find credentials elsewhere (an Anthropic profile, Google Cloud credentials).
+  if (!opts.client && !opts.name && !opts.baseUrl && !hasApiKey(env)) throw Object.assign(new Error(NO_API_KEY), { code: "NO_API_KEY" });
   if (name === "openai-compatible") {
     const baseURL = opts.baseUrl ?? env.OPENAI_COMPATIBLE_BASE_URL;
     const model = opts.model ?? env.OPENAI_COMPATIBLE_MODEL;