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

package/src/guard.js

@@ -0,0 +1,129 @@
+// Limits where the audit browser may go: only http(s), only the audited site
+// (plus any hosts the user allows), and, when asked, never private network addresses.
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+/** Lowercase host without a leading "www.", so www.example.com and example.com match each other. */
+const baseHost = (host) => host.toLowerCase().replace(/^www\./, "");
+
+/**
+ * Hosts the browser may navigate to: the audited site and its subdomains, plus
+ * each allowed host and its subdomains. Entries may be hosts or full URLs.
+ * @param {string} site
+ * @param {string[]} [allowedHosts]
+ */
+export function hostScope(site, allowedHosts = []) {
+  const bases = [site, ...allowedHosts]
+    .map((entry) => String(entry).trim())
+    .filter(Boolean)
+    .map((entry) => {
+      try {
+        return baseHost(new URL(entry.includes("://") ? entry : `http://${entry}`).hostname);
+      } catch {
+        throw new Error(`"${entry}" in allowed_hosts is not a valid host.`);
+      }
+    })
+    .map((h) => h.replace(/^\*\./, ""));
+  return {
+    hosts: [...new Set(bases)],
+    allows(hostname) {
+      const h = hostname.toLowerCase();
+      return this.hosts.some((b) => h === b || h === `www.${b}` || h.endsWith(`.${b}`));
+    },
+  };
+}
+
+function ipv4Private(ip) {
+  const [a, b] = ip.split(".").map(Number);
+  return (
+    a === 0 || a === 10 || a === 127 || a >= 224 ||
+    (a === 100 && b >= 64 && b <= 127) || // carrier-grade NAT
+    (a === 169 && b === 254) || // link-local, cloud metadata
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 192 && b === 0) ||
+    (a === 198 && (b === 18 || b === 19))
+  );
+}
+
+/** The 8 groups of an IPv6 address as numbers, including a trailing dotted IPv4 part, or null. */
+function ipv6Groups(ip) {
+  let a = ip.toLowerCase().replace(/^\[|\]$/g, "").split("%")[0];
+  const v4 = a.match(/(\d+\.\d+\.\d+\.\d+)$/);
+  if (v4) {
+    const [w, x, y, z] = v4[1].split(".").map(Number);
+    a = a.slice(0, -v4[1].length) + `${((w << 8) | x).toString(16)}:${((y << 8) | z).toString(16)}`;
+  }
+  const [head, tail] = a.includes("::") ? a.split("::") : [a, null];
+  const h = head ? head.split(":") : [];
+  const t = tail ? tail.split(":") : [];
+  const groups = tail === null ? h : [...h, ...Array(8 - h.length - t.length).fill("0"), ...t];
+  return groups.length === 8 ? groups.map((g) => parseInt(g || "0", 16)) : null;
+}
+
+const v4From = (hi, lo) => `${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`;
+
+/**
+ * True for loopback, private, link-local, carrier-grade NAT and other non-public
+ * addresses, including IPv6 forms that carry an IPv4 address inside.
+ */
+export function isPrivateAddress(ip) {
+  const v = isIP(String(ip).replace(/^\[|\]$/g, "").split("%")[0]);
+  if (v === 4) return ipv4Private(ip);
+  if (v !== 6) return false;
+  const g = ipv6Groups(ip);
+  if (!g) return true;
+  const [g0, g1, g2, g3, , g5, g6, g7] = g;
+  const zeroTo = (n) => g.slice(0, n).every((x) => x === 0);
+  if (zeroTo(8) || (zeroTo(7) && g7 === 1)) return true; // :: and ::1
+  if (zeroTo(5) && g5 === 0xffff) return ipv4Private(v4From(g6, g7)); // ::ffff:a.b.c.d
+  if (zeroTo(6)) return ipv4Private(v4From(g6, g7)); // ::a.b.c.d (IPv4-compatible)
+  if (g0 === 0x64 && g1 === 0xff9b) return ipv4Private(v4From(g6, g7)); // NAT64 64:ff9b::/96 (and the local-use /48)
+  if (g0 === 0x2002) return ipv4Private(v4From(g1, g2)); // 6to4
+  if (g0 === 0x2001 && g1 === 0) return true; // Teredo: the IPv4 address is obscured, so refuse
+  return (g0 & 0xfe00) === 0xfc00 || (g0 & 0xffc0) === 0xfe80 || (g0 & 0xff00) === 0xff00 || (g0 === 0x100 && g1 === 0 && g2 === 0 && g3 === 0); // ULA, link-local, multicast, discard
+}
+
+/**
+ * Resolves a hostname and reports whether it points at a private address.
+ * Results are cached per checker. This is the early, friendly check; the egress
+ * proxy (egress.js) is what makes sure the browser only connects to checked addresses.
+ */
+export function privateHostChecker(isBlocked = isPrivateAddress) {
+  const cache = new Map();
+  return async (hostname) => {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host.endsWith(".localhost")) return true;
+    if (isIP(host)) return isBlocked(host);
+    if (!cache.has(host)) {
+      cache.set(
+        host,
+        lookup(host, { all: true, verbatim: true })
+          .then((addrs) => addrs.some((a) => isBlocked(a.address)))
+          .catch(() => false), // unresolvable: the browser will fail to load it anyway
+      );
+    }
+    return cache.get(host);
+  };
+}
+
+/**
+ * Checks a navigation target. Returns an error message, or null when allowed.
+ * @param {string} url
+ * @param {{ scope?: ReturnType<typeof hostScope>, isPrivate?: (host: string) => Promise<boolean> }} rules
+ */
+export async function navigationError(url, { scope, isPrivate } = {}) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return `"${url}" is not a valid URL.`;
+  }
+  if (u.protocol === "about:" && u.href === "about:blank") return null;
+  if (!["http:", "https:"].includes(u.protocol)) return `Only http and https pages can be opened, not ${u.protocol} URLs.`;
+  if (scope && !scope.allows(u.hostname)) {
+    return `${u.hostname} is outside the audited site (${scope.hosts.join(", ")}). Stay on the site. If the journey really needs this host (for example a hosted checkout), add it to allowed_hosts.`;
+  }
+  if (isPrivate && (await isPrivate(u.hostname))) return `${u.hostname} is a private network address, which this server doesn't open.`;
+  return null;
+}

package/src/i18n.js

@@ -0,0 +1,207 @@
+// Report language strings. Add a language by copying the "en" block.
+
+const q = (s) => `"${s}"`;
+
+const en = {
+  name: "English",
+  severity: { broken: "Broken", risk: "Risk", warning: "Warning", info: "Info", ok: "OK" },
+  ui: {
+    title: (host) => `AI Tag Debugger report: ${host}`,
+    generated: (at) => `Generated ${at} by ai-tag-debugger · Analitik İşler`,
+    summary: "Summary",
+    eyebrow: "Tracking QA report",
+    paramsShort: "params",
+    noParameters: "No parameters.",
+    pushMatchHint: "dataLayer pushes in this step with the same event name.",
+    noMatchingPush: "No dataLayer push with this event name in this step. The tag may fire from a page view, a click trigger or a hardcoded pixel.",
+    otherInStep: "Other dataLayer pushes and network calls",
+    noHits: "No tracking events",
+    hasProblems: "Has problems",
+    stepsShort: "steps",
+    eventsShort: "events",
+    problemsShort: "problems",
+    findings: "Findings",
+    what: "What",
+    where: "Where",
+    causeAndFix: "Cause and fix",
+    likelyCause: "Likely cause",
+    fix: "Fix",
+    captured: "Captured",
+    noProblems: "No problems found.",
+    noExplanation: "Run without --no-ai for an explanation.",
+    matchingPlan: "Matching the plan",
+    timeline: "Journeys and event timeline",
+    timelineLead: "Every step of every journey. Events are grouped by platform; open one to see its parameters, the dataLayer push behind it and the network request that carried it. Steps with problems are open.",
+    completed: "Completed",
+    notCompleted: "Not completed",
+    step: "step",
+    trackingHits: "Tracking hits",
+    dataLayer: "dataLayer pushes",
+    network: "Network calls",
+    platform: "Platform",
+    event: "Event",
+    parameters: "Parameters",
+    consent: "Consent",
+    method: "Method",
+    status: "Status",
+    vendor: "Vendor",
+    blockedNote: "answered locally, not sent",
+    clickedThrough: "clicked through an overlapping element",
+    generatedBy: "Generated by AI Tag Debugger",
+    nothing: "None",
+    counts: (c) => `${c.broken} broken · ${c.risk} risk · ${c.warning} warning · ${c.info} info · ${c.ok} ok`,
+    whereStep: (journey, viewport, step) => `${journey} (${viewport})${step ? `, step "${step}"` : ""}`,
+    allGood: "All planned events fired correctly on every journey tested.",
+    tabEvents: "Events",
+    bodyDropped: "Request body not stored: this audit reached its 2 MB limit for stored request bodies.",
+    tabNetwork: "Network requests",
+    filterBy: "Filter by source",
+    all: "All",
+    items: "Items",
+    customItemParams: "Custom item parameters",
+    itemsCount: (n) => `${n} ${n === 1 ? "item" : "items"}`,
+    noItems: "no items",
+    source: "Source",
+    request: "Request",
+    noRequest: "No matching request",
+    noPushes: "No dataLayer pushes in this step.",
+    noRequests: "No requests to the chosen providers in this step.",
+    eventParams: "Event parameters",
+    contextParams: "Session, device, page and consent parameters",
+    rawRequest: "Raw request",
+    rawJson: "Raw JSON",
+    inBatch: (i, n) => `${i} of ${n} in one request`,
+    impact: "Impact",
+    evidence: "Evidence",
+    fixSteps: "Fix",
+    places: (n) => `${n} ${n === 1 ? "place" : "places"}`,
+    alsoCheck: "Not in the findings list, but worth checking",
+    providersChecked: "Providers checked:",
+    outOfScope: (list, n) => `Out of scope: ${list} (${n} ${n === 1 ? "request" : "requests"} skipped)`,
+    skippedInStep: (list, n) => `Only requests to the chosen providers are shown. ${n} out-of-scope ${n === 1 ? "request was" : "requests were"} skipped in this step: ${list}.`,
+    timelineLeadV2: "Every step has three tabs: the events it sent, its dataLayer pushes and its network requests. Events and requests can be filtered by source. Steps with problems are open.",
+  },
+  detail: {
+    journeyIncomplete: (note) => `The journey did not reach its goal${note ? `: ${note}` : "."} Events after that point could not be checked.`,
+    missingEvent: (platform, name) => `Expected ${platform} event ${q(name)} was never sent during this journey.`,
+    missingEventEarly: (name) => `${q(name)} was not seen, but the journey stopped early, so this may not be a tracking bug.`,
+    missingParams: (name, params) => `${q(name)} was sent without ${params.map(q).join(", ")}.`,
+    duplicate: (name, n) => `${q(name)} was sent ${n} times by one action, which inflates counts and conversions.`,
+    consentDefaultMissing: () => "No Google Consent Mode default command (gtag('consent', 'default', ...)) was found in the dataLayer.",
+    consentDefaultLate: () => "The Consent Mode default was set after the first tracking hit was sent.",
+    beforeConsentNever: (platform, name) => `${platform} ${q(name)} fired although consent was never given in this journey.`,
+    beforeConsent: (platform, name) => `${platform} ${q(name)} fired before the visitor accepted cookies.`,
+    pii: (platform, name) => `An email address was sent in plain text with ${q(name)} to ${platform}.`,
+    unplanned: (list) => `Events sent that are not in the measurement plan: ${list.join(", ")}.`,
+    piiUnhashed: (platform, name, fields) => `${q(name)} sent user data to ${platform} without hashing it (${fields.join(", ")}). Ad platforms expect these values SHA-256 hashed.`,
+    piiDataLayer: (fields) => `The dataLayer holds user data that isn't hashed (${fields.join(", ")}). This is a valid setup for Google enhanced conversions, but every other tag and script on the page can read it too. Check that only the tags that should use it do.`,
+    plannedOutOfScope: (list) => `${list.length} planned ${list.length === 1 ? "event was" : "events were"} not checked because the provider wasn't selected: ${list.join(", ")}. Add the provider with --providers to check ${list.length === 1 ? "it" : "them"}.`,
+    matches: (list) => `${list.length} planned events matched the plan: ${list.join(", ")}.`,
+  },
+};
+
+const tr = {
+  name: "Turkish",
+  severity: { broken: "Bozuk", risk: "Risk", warning: "Uyarı", info: "Bilgi", ok: "Tamam" },
+  ui: {
+    title: (host) => `AI Tag Debugger raporu: ${host}`,
+    generated: (at) => `${at} tarihinde ai-tag-debugger ile oluşturuldu · Analitik İşler`,
+    summary: "Özet",
+    eyebrow: "İzleme QA raporu",
+    paramsShort: "parametre",
+    noParameters: "Parametre yok.",
+    pushMatchHint: "Bu adımda aynı olay adına sahip dataLayer gönderimleri.",
+    noMatchingPush: "Bu adımda bu olay adıyla bir dataLayer gönderimi yok. Etiket bir sayfa görüntüleme, tıklama tetikleyicisi ya da sayfaya gömülü bir pikselden tetikleniyor olabilir.",
+    otherInStep: "Diğer dataLayer gönderimleri ve ağ çağrıları",
+    noHits: "İzleme olayı yok",
+    hasProblems: "Sorun var",
+    stepsShort: "adım",
+    eventsShort: "olay",
+    problemsShort: "sorun",
+    findings: "Bulgular",
+    what: "Ne",
+    where: "Nerede",
+    causeAndFix: "Neden ve çözüm",
+    likelyCause: "Olası neden",
+    fix: "Çözüm",
+    captured: "Yakalanan",
+    noProblems: "Sorun bulunamadı.",
+    noExplanation: "Açıklama için --no-ai olmadan çalıştırın.",
+    matchingPlan: "Plana uygun olanlar",
+    timeline: "Yolculuklar ve olay zaman çizelgesi",
+    timelineLead: "Her yolculuğun her adımı. Olaylar platforma göre gruplanır; bir olayı açınca parametrelerini, arkasındaki dataLayer gönderimini ve onu taşıyan ağ isteğini görürsünüz. Sorunlu adımlar açık gösterilir.",
+    completed: "Tamamlandı",
+    notCompleted: "Tamamlanmadı",
+    step: "adım",
+    trackingHits: "İzleme istekleri",
+    dataLayer: "dataLayer gönderimleri",
+    network: "Ağ çağrıları",
+    platform: "Platform",
+    event: "Olay",
+    parameters: "Parametreler",
+    consent: "Onay",
+    method: "Metot",
+    status: "Durum",
+    vendor: "Sağlayıcı",
+    blockedNote: "yerel olarak yanıtlandı, gönderilmedi",
+    clickedThrough: "üstündeki bir öğeye rağmen tıklandı",
+    generatedBy: "AI Tag Debugger ile oluşturuldu",
+    nothing: "Yok",
+    counts: (c) => `${c.broken} bozuk · ${c.risk} risk · ${c.warning} uyarı · ${c.info} bilgi · ${c.ok} tamam`,
+    whereStep: (journey, viewport, step) => `${journey} (${viewport})${step ? `, "${step}" adımı` : ""}`,
+    allGood: "Test edilen tüm yolculuklarda plandaki tüm olaylar doğru çalıştı.",
+    tabEvents: "Olaylar",
+    bodyDropped: "İstek gövdesi saklanmadı: bu denetim, saklanan istek gövdeleri için 2 MB sınırına ulaştı.",
+    tabNetwork: "Ağ istekleri",
+    filterBy: "Kaynağa göre filtrele",
+    all: "Tümü",
+    items: "Ürünler",
+    customItemParams: "Özel ürün parametreleri",
+    itemsCount: (n) => `${n} ürün`,
+    noItems: "ürün yok",
+    source: "Kaynak",
+    request: "İstek",
+    noRequest: "Eşleşen istek yok",
+    noPushes: "Bu adımda dataLayer gönderimi yok.",
+    noRequests: "Bu adımda seçilen sağlayıcılara istek yok.",
+    eventParams: "Olay parametreleri",
+    contextParams: "Oturum, cihaz, sayfa ve onay parametreleri",
+    rawRequest: "Ham istek",
+    rawJson: "Ham JSON",
+    inBatch: (i, n) => `tek istekte ${n} olaydan ${i}.`,
+    impact: "Etkisi",
+    evidence: "Kanıt",
+    fixSteps: "Çözüm",
+    places: (n) => `${n} yer`,
+    alsoCheck: "Bulgu listesinde olmayan, ama kontrol edilmesi gerekenler",
+    providersChecked: "Kontrol edilen sağlayıcılar:",
+    outOfScope: (list, n) => `Kapsam dışı: ${list} (${n} istek atlandı)`,
+    skippedInStep: (list, n) => `Yalnızca seçilen sağlayıcıların istekleri gösterilir. Bu adımda kapsam dışı ${n} istek atlandı: ${list}.`,
+    timelineLeadV2: "Her adımda üç sekme var: o adımda gönderilen olaylar, dataLayer gönderimleri ve ağ istekleri. Olayları ve istekleri kaynağa göre filtreleyebilirsiniz. Sorunlu adımlar açık gösterilir.",
+  },
+  detail: {
+    journeyIncomplete: (note) => `Yolculuk hedefine ulaşmadı${note ? `: ${note}` : "."} Bu noktadan sonraki olaylar kontrol edilemedi.`,
+    missingEvent: (platform, name) => `Beklenen ${platform} olayı ${q(name)} bu yolculuk boyunca hiç gönderilmedi.`,
+    missingEventEarly: (name) => `${q(name)} görülmedi, ancak yolculuk erken durduğu için bu bir izleme hatası olmayabilir.`,
+    missingParams: (name, params) => `${q(name)} olayı ${params.map(q).join(", ")} ${params.length > 1 ? "parametreleri" : "parametresi"} olmadan gönderildi.`,
+    duplicate: (name, n) => `${q(name)} tek bir işlemde ${n} kez gönderildi; bu da sayıları ve dönüşümleri şişirir.`,
+    consentDefaultMissing: () => "dataLayer'da Google Consent Mode varsayılan komutu (gtag('consent', 'default', ...)) bulunamadı.",
+    consentDefaultLate: () => "Consent Mode varsayılanı, ilk izleme isteği gönderildikten sonra ayarlandı.",
+    beforeConsentNever: (platform, name) => `${platform} ${q(name)}, bu yolculukta hiç onay verilmemesine rağmen tetiklendi.`,
+    beforeConsent: (platform, name) => `${platform} ${q(name)}, ziyaretçi çerezleri kabul etmeden önce tetiklendi.`,
+    pii: (platform, name) => `${q(name)} ile birlikte ${platform} platformuna düz metin olarak bir e-posta adresi gönderildi.`,
+    unplanned: (list) => `Ölçüm planında olmayan olaylar gönderildi: ${list.join(", ")}.`,
+    piiUnhashed: (platform, name, fields) => `${q(name)}, ${platform} platformuna kullanıcı verisini karma (hash) yapmadan gönderdi (${fields.join(", ")}). Reklam platformları bu değerleri SHA-256 ile karma yapılmış bekler.`,
+    piiDataLayer: (fields) => `dataLayer karma (hash) yapılmamış kullanıcı verisi içeriyor (${fields.join(", ")}). Bu, Google gelişmiş dönüşümleri için geçerli bir kurulum, ancak sayfadaki diğer tüm etiketler ve betikler de bu veriyi okuyabilir. Yalnızca kullanması gereken etiketlerin kullandığını kontrol edin.`,
+    plannedOutOfScope: (list) => `Plandaki ${list.length} olay, sağlayıcısı seçilmediği için kontrol edilmedi: ${list.join(", ")}. Kontrol etmek için sağlayıcıyı --providers ile ekleyin.`,
+    matches: (list) => `Plandaki ${list.length} olay plana uygun çalıştı: ${list.join(", ")}.`,
+  },
+};
+
+export const LANGUAGES = { en, tr };
+
+export function messages(lang = "en") {
+  const m = LANGUAGES[lang];
+  if (!m) throw new Error(`Unsupported language "${lang}". Use: ${Object.keys(LANGUAGES).join(", ")}`);
+  return m;
+}

package/src/journeys.js

@@ -0,0 +1,138 @@
+// Ready-made journeys: a goal for the AI in plain language, plus the events
+// (GA4 recommended events and Meta standard events) a correct setup sends on the way.
+// They let you audit a site without writing a config or a measurement plan.
+
+const ecommerce = ["currency", "value", "items"];
+
+export const JOURNEY_PRESETS = {
+  purchase: {
+    goal: "Accept cookies, open any product, add it to the cart, go to checkout and place the order with the test or demo payment option until a confirmation page shows. Never enter real payment details.",
+    events: [
+      { platform: "ga4", name: "view_item", required_params: ecommerce },
+      { platform: "ga4", name: "add_to_cart", required_params: ecommerce },
+      { platform: "ga4", name: "begin_checkout", required_params: ecommerce },
+      { platform: "ga4", name: "purchase", required_params: ["transaction_id", ...ecommerce] },
+      { platform: "meta", name: "AddToCart" },
+      { platform: "meta", name: "InitiateCheckout" },
+      { platform: "meta", name: "Purchase", required_params: ["value", "currency"] },
+    ],
+  },
+  add_to_cart: {
+    goal: "Accept cookies, open any product and add it to the cart. Stop once the cart shows the product.",
+    events: [
+      { platform: "ga4", name: "view_item", required_params: ecommerce },
+      { platform: "ga4", name: "add_to_cart", required_params: ecommerce },
+      { platform: "meta", name: "AddToCart" },
+    ],
+  },
+  sign_up: {
+    goal: "Accept cookies, find the sign-up or registration form, and create an account with the test data. Stop when the site confirms the account or asks to verify the email.",
+    events: [
+      { platform: "ga4", name: "sign_up" },
+      { platform: "meta", name: "CompleteRegistration" },
+    ],
+  },
+  lead: {
+    goal: "Accept cookies, find a contact, quote or demo request form, fill it in with the test data and submit it. Stop when the site confirms the submission.",
+    events: [
+      { platform: "ga4", name: "generate_lead" },
+      { platform: "meta", name: "Lead" },
+    ],
+  },
+  search: {
+    goal: "Accept cookies, use the site search to search for a common product or topic, and open the first result.",
+    events: [
+      { platform: "ga4", name: "search", required_params: ["search_term"] },
+      { platform: "meta", name: "Search" },
+    ],
+  },
+};
+
+const ALIASES = { checkout: "purchase", order: "purchase", cart: "add_to_cart", signup: "sign_up", 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) {
+  const id = ALIASES[name?.toLowerCase()] ?? name?.toLowerCase();
+  return JOURNEY_PRESETS[id] ? { id, ...JOURNEY_PRESETS[id] } : null;
+}
+
+/**
+ * Adds a journey's preset events to a plan (a copy): events the plan already
+ * has are expected on this journey too; missing ones are added for this journey.
+ */
+export function withPresetEvents(plan, journeyId, preset) {
+  const events = plan.events.map((e) => ({ ...e }));
+  for (const pe of preset.events) {
+    const existing = events.find((e) => e.platform === pe.platform && e.name === pe.name);
+    if (!existing) events.push({ ...pe, journeys: [journeyId] });
+    else if (existing.journeys && !existing.journeys.includes(journeyId)) existing.journeys = [...existing.journeys, journeyId];
+  }
+  return { ...plan, events };
+}
+
+/**
+ * Builds the journeys and plan for a run from the config plus command-line picks.
+ * @param {{ config?: any, plan?: any, picks?: string[], goals?: string[], events?: string[] }} opts
+ *   picks: journey ids from the config or preset names. goals: journeys described in plain language.
+ *   events: only check these event names.
+ */
+export function planRun({ config = {}, plan, picks = [], goals = [], events = [] }) {
+  // Copied, because the loops below add journeys to events.
+  let runPlan = { ...(plan ?? { events: [] }), events: (plan?.events ?? []).map((e) => ({ ...e })) };
+  const configJourneys = config.journeys ?? [];
+  const journeys = [];
+
+  for (const pick of picks) {
+    const fromConfig = configJourneys.find((j) => j.id === pick);
+    if (fromConfig) {
+      journeys.push(fromConfig);
+      continue;
+    }
+    const preset = presetFor(pick);
+    if (!preset) {
+      const known = [...configJourneys.map((j) => j.id), ...Object.keys(JOURNEY_PRESETS)];
+      throw new Error(`Unknown journey "${pick}". Use one of: ${[...new Set(known)].join(", ")}, or describe it with --goal.`);
+    }
+    if (journeys.some((j) => j.id === preset.id)) continue;
+    journeys.push({ id: preset.id, goal: preset.goal });
+    runPlan = withPresetEvents(runPlan, preset.id, preset);
+  }
+
+  goals.forEach((goal, i) => {
+    const id = goals.length > 1 ? `custom-${i + 1}` : "custom";
+    journeys.push({ id, goal });
+    runPlan = expectEvents(runPlan, id, events);
+  });
+
+  if (!picks.length && !goals.length) journeys.push(...configJourneys);
+
+  return { journeys, plan: onlyEvents(runPlan, events) };
+}
+
+/** Keeps only the picked events in a plan (all of them when none are picked). Names match any platform, ignoring case. */
+export function onlyEvents(plan, events = []) {
+  if (!events.length) return plan;
+  const wanted = new Set(events.map((e) => e.toLowerCase()));
+  return { ...plan, events: plan.events.filter((e) => wanted.has(e.name.toLowerCase())) };
+}
+
+/**
+ * A journey you describe yourself has no known events, so the events you pick are
+ * expected on it: as GA4 events, unless the plan already lists them.
+ */
+export function expectEvents(plan, journeyId, names) {
+  const events = plan.events.map((e) => ({ ...e }));
+  for (const name of names) {
+    const existing = events.filter((e) => e.name.toLowerCase() === name.toLowerCase());
+    if (!existing.length) events.push({ platform: "ga4", name, journeys: [journeyId] });
+    for (const e of existing) if (e.journeys && !e.journeys.includes(journeyId)) e.journeys = [...e.journeys, journeyId];
+  }
+  return { ...plan, events };
+}
+
+/** With an events filter, keeps findings about those events plus the journey-wide ones (consent setup, incomplete journey). */
+export function filterFindings(findings, events = []) {
+  if (!events.length) return findings;
+  const wanted = new Set(events.map((e) => e.toLowerCase()));
+  return findings.filter((f) => (f.event ? wanted.has(f.event.toLowerCase()) : f.check !== "unplanned_events"));
+}