@detiq/crawler 0.1.3

package/src/feature-flag-detector.ts

@@ -0,0 +1,97 @@
+/**
+ * Feature flag + A/B test detector.
+ *
+ * Detects popular feature flag / experiment SDKs loaded on the page:
+ * LaunchDarkly, Optimizely, Split.io, Unleash, GrowthBook, Statsig, Flagsmith, Amplitude Experiment.
+ *
+ * Also detects common A/B test patterns: data-testid attributes, gtm.js experiment layers,
+ * Optimizely variation IDs, VWO, etc.
+ *
+ * Why: ZeTa needs to know when a page shows different content to different users
+ * so test generation can account for variants and not generate flaky tests.
+ */
+
+import type { Page } from 'playwright';
+
+export interface FeatureFlagInfo {
+  sdk: string;
+  confidence: 'high' | 'medium' | 'low';
+  details?: string;
+}
+
+export interface AbTestInfo {
+  tool: string;
+  experiments?: string[];
+}
+
+export interface FeatureFlagDetectionResult {
+  url: string;
+  flagSdks: FeatureFlagInfo[];
+  abTools: AbTestInfo[];
+  hasAnyFlags: boolean;
+  detectedAt: string;
+}
+
+// SDK detectors — checked against window object + script URLs
+const FLAG_SDK_CHECKS: Array<{
+  sdk: string;
+  windowKeys?: string[];
+  scriptPattern?: RegExp;
+}> = [
+  { sdk: 'LaunchDarkly', windowKeys: ['LDClient', 'LaunchDarkly', 'ldClient'], scriptPattern: /launchdarkly/i },
+  { sdk: 'Optimizely', windowKeys: ['optimizely', 'optimizelySdk'], scriptPattern: /optimizely/i },
+  { sdk: 'Split.io', windowKeys: ['splitio', 'SplitFactory'], scriptPattern: /split\.io/i },
+  { sdk: 'GrowthBook', windowKeys: ['growthbook', 'GrowthBook'], scriptPattern: /growthbook/i },
+  { sdk: 'Statsig', windowKeys: ['statsig', 'StatsigClient'], scriptPattern: /statsig/i },
+  { sdk: 'Flagsmith', windowKeys: ['flagsmith'], scriptPattern: /flagsmith/i },
+  { sdk: 'Unleash', windowKeys: ['unleash', 'UnleashClient'], scriptPattern: /unleash/i },
+  { sdk: 'VWO', windowKeys: ['vwo', '_vwo'], scriptPattern: /vwo\.com/i },
+  { sdk: 'Google Optimize', windowKeys: ['gaData', 'google_optimize'], scriptPattern: /googleoptimize/i },
+  { sdk: 'AB Tasty', windowKeys: ['ABTasty'], scriptPattern: /abtasty/i },
+];
+
+export async function detectFeatureFlags(page: Page, url: string): Promise<FeatureFlagDetectionResult> {
+  const detectedAt = new Date().toISOString();
+
+  const result = await page.evaluate((checks) => {
+    const flagSdks: any[] = [];
+    const scripts = Array.from(document.querySelectorAll('script[src]')).map((s: any) => s.src ?? '');
+
+    for (const check of checks) {
+      let found = false;
+      let confidence = 'low';
+
+      // Check window keys
+      if (check.windowKeys?.some((k: string) => k in (window as any))) {
+        found = true;
+        confidence = 'high';
+      }
+      // Check script URLs
+      if (!found && check.scriptPattern) {
+        const re = new RegExp(check.scriptPattern.source, 'i');
+        const matchingSrc = scripts.find(s => re.test(s));
+        if (matchingSrc) { found = true; confidence = 'medium'; }
+      }
+      if (found) flagSdks.push({ sdk: check.sdk, confidence, details: undefined });
+    }
+
+    // A/B tools
+    const abTools: any[] = [];
+    if ('_vwo_code' in window || '_vis_opt_queue' in (window as any)) abTools.push({ tool: 'VWO', experiments: [] });
+    if ('dataLayer' in window) {
+      const dl = (window as any).dataLayer ?? [];
+      const expEvents = dl.filter((e: any) => e?.event?.includes('experiment') || e?.experimentId);
+      if (expEvents.length > 0) abTools.push({ tool: 'Google Tag Manager Experiments', experiments: expEvents.slice(0, 5).map((e: any) => e.experimentId ?? '') });
+    }
+
+    return { flagSdks, abTools };
+  }, FLAG_SDK_CHECKS as any).catch(() => ({ flagSdks: [], abTools: [] }));
+
+  return {
+    url,
+    flagSdks: result.flagSdks,
+    abTools: result.abTools,
+    hasAnyFlags: result.flagSdks.length > 0 || result.abTools.length > 0,
+    detectedAt,
+  };
+}

package/src/form-detector.ts

@@ -0,0 +1,103 @@
+/**
+ * Form detector — extract form metadata from crawled pages.
+ *
+ * For each form found on a page, captures: action URL, method, all input fields
+ * with their types/names/required/validation constraints, and submit button text.
+ *
+ * This data feeds ZeTa's test generator to create form validation test cases
+ * automatically (happy path + boundary/error cases per field type).
+ */
+
+import type { Page } from 'playwright';
+
+export interface FormField {
+  name: string;
+  type: string;        // text, email, password, number, select, textarea, checkbox, radio, file, date
+  label?: string;
+  required: boolean;
+  placeholder?: string;
+  minLength?: number;
+  maxLength?: number;
+  min?: string;
+  max?: string;
+  pattern?: string;
+  options?: string[]; // for select/radio
+  autocomplete?: string;
+}
+
+export interface DetectedForm {
+  index: number;
+  action?: string;
+  method: string;
+  fields: FormField[];
+  submitText?: string;
+  hasFileUpload: boolean;
+  purpose: 'login' | 'search' | 'registration' | 'contact' | 'checkout' | 'settings' | 'unknown';
+}
+
+function guessPurpose(fields: FormField[], action?: string): DetectedForm['purpose'] {
+  const names = fields.map(f => f.name?.toLowerCase() + (f.label ?? '').toLowerCase()).join(' ');
+  if (/password/.test(names) && /email|username|user/.test(names) && fields.length <= 4) return 'login';
+  if (/password/.test(names) && /confirm|repeat/.test(names)) return 'registration';
+  if (/search|query|q\b/.test(names) && fields.length <= 3) return 'search';
+  if (/card|payment|cvv|expir/.test(names)) return 'checkout';
+  if (/message|subject|contact/.test(names)) return 'contact';
+  if (/setting|preference|profile/.test(names)) return 'settings';
+  return 'unknown';
+}
+
+export async function detectForms(page: Page): Promise<DetectedForm[]> {
+  try {
+    return await page.$$eval('form', (forms) => forms.map((form: any, index: number) => {
+      const inputs = Array.from(form.querySelectorAll('input,select,textarea,button[type="submit"]'));
+      const fields: any[] = [];
+
+      for (const input of inputs as any[]) {
+        const tag = input.tagName.toLowerCase();
+        const type = tag === 'button' ? 'submit' : (input.type || tag);
+        if (['submit', 'reset', 'button', 'hidden'].includes(type)) continue;
+
+        // Find associated label
+        let label = '';
+        if (input.id) {
+          const lbl = form.querySelector(`label[for="${input.id}"]`);
+          if (lbl) label = (lbl.textContent ?? '').trim();
+        }
+        if (!label) {
+          const parent = input.closest('label');
+          if (parent) label = (parent.textContent ?? '').replace(input.value ?? '', '').trim().slice(0, 80);
+        }
+
+        const options = tag === 'select'
+          ? Array.from(input.options ?? []).map((o: any) => o.text?.trim()).filter(Boolean).slice(0, 20)
+          : tag === 'input' && type === 'radio'
+          ? [input.value]
+          : undefined;
+
+        fields.push({
+          name: input.name || input.id || '',
+          type,
+          label: label || undefined,
+          required: !!input.required,
+          placeholder: input.placeholder || undefined,
+          minLength: input.minLength > 0 ? input.minLength : undefined,
+          maxLength: input.maxLength > 0 && input.maxLength < 524288 ? input.maxLength : undefined,
+          min: input.min || undefined,
+          max: input.max || undefined,
+          pattern: input.pattern || undefined,
+          options,
+          autocomplete: input.autocomplete || undefined,
+        });
+      }
+
+      const submitBtn = form.querySelector('button[type="submit"],input[type="submit"]') as any;
+      const hasFileUpload = !!form.querySelector('input[type="file"]');
+      const action = form.action || undefined;
+      const method = (form.method || 'get').toUpperCase();
+
+      return { index, action, method, fields, submitText: submitBtn?.textContent?.trim() || submitBtn?.value || undefined, hasFileUpload };
+    })).then(forms => forms.map((f: any) => ({ ...f, purpose: guessPurpose(f.fields, f.action) })));
+  } catch {
+    return [];
+  }
+}

package/src/frontier.test.ts

@@ -0,0 +1,64 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { CrawlFrontier } from './frontier.js';
+
+test('CrawlFrontier: BFS dequeues in FIFO order, identical to a plain array shift()', () => {
+  const f = new CrawlFrontier('BFS', ['https://a.com/1', 'https://a.com/2']);
+  f.push('https://a.com/3');
+  assert.equal(f.shift(), 'https://a.com/1');
+  assert.equal(f.shift(), 'https://a.com/2');
+  assert.equal(f.shift(), 'https://a.com/3');
+  assert.equal(f.shift(), undefined);
+});
+
+test('CrawlFrontier: DFS dequeues in LIFO order', () => {
+  const f = new CrawlFrontier('DFS', ['https://a.com/1', 'https://a.com/2']);
+  f.push('https://a.com/3');
+  assert.equal(f.shift(), 'https://a.com/3');
+  assert.equal(f.shift(), 'https://a.com/2');
+  assert.equal(f.shift(), 'https://a.com/1');
+});
+
+test('CrawlFrontier: BEST_FIRST prefers shallower paths over deeper ones', () => {
+  const f = new CrawlFrontier('BEST_FIRST', [
+    'https://a.com/products/electronics/phones/model-x',
+    'https://a.com/about',
+  ]);
+  assert.equal(f.shift(), 'https://a.com/about');
+  assert.equal(f.shift(), 'https://a.com/products/electronics/phones/model-x');
+});
+
+test('CrawlFrontier: BEST_FIRST boosts URLs matching keywords ahead of shallower non-matching ones', () => {
+  const f = new CrawlFrontier('BEST_FIRST', ['https://a.com/'], ['pricing']);
+  f.push('https://a.com/deep/nested/pricing/plans');
+  // "/" has depth 0 (score 0); the pricing URL has depth 4 (score -4) but +10 for the
+  // keyword match, netting +6 — the keyword-matching page should win despite depth.
+  assert.equal(f.shift(), 'https://a.com/deep/nested/pricing/plans');
+  assert.equal(f.shift(), 'https://a.com/');
+});
+
+test('CrawlFrontier: length reflects push/shift correctly across all strategies', () => {
+  for (const strategy of ['BFS', 'DFS', 'BEST_FIRST'] as const) {
+    const f = new CrawlFrontier(strategy, ['https://a.com/1']);
+    assert.equal(f.length, 1);
+    f.push('https://a.com/2');
+    assert.equal(f.length, 2);
+    f.shift();
+    assert.equal(f.length, 1);
+  }
+});
+
+test('CrawlFrontier: filter returns URLs matching the predicate without mutating the frontier', () => {
+  const f = new CrawlFrontier('BFS', ['https://a.com/1', 'https://a.com/2', 'https://a.com/3']);
+  const matched = f.filter((u) => u.endsWith('/2'));
+  assert.deepEqual(matched, ['https://a.com/2']);
+  assert.equal(f.length, 3); // unchanged
+});
+
+test('CrawlFrontier: malformed URLs never throw when scored under BEST_FIRST', () => {
+  assert.doesNotThrow(() => {
+    const f = new CrawlFrontier('BEST_FIRST', ['not-a-valid-url', 'https://a.com/ok']);
+    f.shift();
+    f.shift();
+  });
+});

package/src/frontier.ts

@@ -0,0 +1,112 @@
+/**
+ * Configurable crawl traversal strategy — matches crawl4AI's BFS/DFS/
+ * Best-First deep-crawl strategies (ZeTa previously had a single hardcoded
+ * FIFO queue, i.e. always BFS).
+ *
+ * Array-like on purpose (`length`, `shift()`, `push()`, `filter()`) so it
+ * drops into crawler.ts's existing queue call sites with a rename, not a
+ * rewrite — BFS's `shift()` behavior is byte-for-byte the same as the plain
+ * array it replaces, so BFS (the default) has zero behavior change.
+ */
+
+export type TraversalStrategy = 'BFS' | 'DFS' | 'BEST_FIRST';
+
+interface FrontierEntry {
+  url: string;
+  score: number;
+}
+
+/**
+ * Best-First scoring heuristic: shallower paths score higher (breadth-like
+ * bias toward top-level sections before deep sub-pages), boosted further by
+ * any user-supplied keyword appearing in the URL. Simple and transparent by
+ * design — crawl4AI's own default scorer is a similarly simple keyword-
+ * relevance heuristic, not a learned model.
+ */
+function scoreUrl(url: string, keywords: string[]): number {
+  try {
+    const u = new URL(url);
+    const segments = u.pathname.split('/').filter(Boolean);
+    let score = -segments.length;
+    if (keywords.length > 0) {
+      const lower = url.toLowerCase();
+      for (const kw of keywords) {
+        if (kw && lower.includes(kw)) score += 10;
+      }
+    }
+    return score;
+  } catch {
+    return 0;
+  }
+}
+
+export class CrawlFrontier {
+  private items: FrontierEntry[] = [];
+  private readonly strategy: TraversalStrategy;
+  private readonly keywords: string[];
+  private readonly urlFilter: RegExp | null;
+
+  constructor(strategy: TraversalStrategy, seedUrls: string[], keywords: string[] = [], urlFilter?: string) {
+    this.strategy = strategy;
+    this.keywords = keywords.map((k) => k.toLowerCase()).filter(Boolean);
+    this.urlFilter = urlFilter
+      ? (() => { try { return new RegExp(urlFilter, 'i'); } catch { return null; } })()
+      : null;
+    for (const url of seedUrls) this.push(url);
+  }
+
+  get length(): number {
+    return this.items.length;
+  }
+
+  /**
+   * P3b: sparse-parent boost — if the parent page had fewer than 5 interactive
+   * elements (thin/canvas page), its child URLs score +1 in BEST_FIRST mode so
+   * the frontier revisits sparse branches before deep-linked content.
+   */
+  push(url: string, pushOpts?: { parentElements?: number }): void {
+    if (this.urlFilter && !this.urlFilter.test(url)) return;
+    const sparseBoost =
+      this.strategy === 'BEST_FIRST' &&
+      pushOpts?.parentElements !== undefined &&
+      pushOpts.parentElements < 5
+        ? 1
+        : 0;
+    this.items.push({ url, score: this.strategy === 'BEST_FIRST' ? scoreUrl(url, this.keywords) + sparseBoost : 0 });
+  }
+
+  /** Dequeues the next URL per this frontier's strategy. undefined if empty. */
+  shift(): string | undefined {
+    if (this.items.length === 0) return undefined;
+    switch (this.strategy) {
+      case 'DFS':
+        return this.items.pop()!.url;
+      case 'BEST_FIRST': {
+        let bestIdx = 0;
+        for (let i = 1; i < this.items.length; i++) {
+          if (this.items[i].score > this.items[bestIdx].score) bestIdx = i;
+        }
+        return this.items.splice(bestIdx, 1)[0].url;
+      }
+      case 'BFS':
+      default:
+        return this.items.shift()!.url;
+    }
+  }
+
+  filter(predicate: (url: string) => boolean): string[] {
+    return this.items.filter((e) => predicate(e.url)).map((e) => e.url);
+  }
+
+  /** Remove queued URLs not matching the regex pattern. Returns count removed. */
+  filterByPattern(pattern: string): number {
+    try {
+      const re = new RegExp(pattern, 'i');
+      const before = this.items.length;
+      this.items = this.items.filter((e) => re.test(e.url));
+      return before - this.items.length;
+    } catch {
+      return 0;
+    }
+  }
+}

package/src/gap-pass.ts

@@ -0,0 +1,122 @@
+/**
+ * P6: Gap Pass — LLM-guided second crawl pass
+ *
+ * After the primary BFS crawl completes, this module:
+ * 1. Sends the discovered screen list to an LLM for gap analysis
+ * 2. HEAD-validates each suggested URL
+ * 3. Returns confirmed gap URLs for targeted re-crawl
+ *
+ * The caller (crawler.ts) is responsible for actually visiting the confirmed
+ * URLs with the existing browser — this module only identifies them.
+ */
+
+import { logger as rootLogger } from './logger.js';
+
+const logger = rootLogger.child({ module: 'gap-pass' });
+
+export interface GapCandidate {
+  category: string;
+  urlPatterns: string[];
+  confidence: number;
+  rationale: string;
+  confirmedUrl: string | null;
+  headStatus: number | null;
+}
+
+interface DiscoveredScreen {
+  url: string;
+  name?: string;
+  elements?: number;
+}
+
+interface LlmCfg {
+  provider: string;
+  model: string;
+  apiKey?: string;
+}
+
+/**
+ * Run LLM gap analysis + HEAD validation.
+ * Returns candidates with `confirmedUrl` set for those where HEAD returned 200.
+ */
+export async function runGapAnalysis(
+  screens: DiscoveredScreen[],
+  appUrl: string,
+  llmCfg: LlmCfg | null | undefined,
+): Promise<GapCandidate[]> {
+  if (!llmCfg?.apiKey || screens.length < 2) return [];
+
+  const origin = (() => { try { return new URL(appUrl).origin; } catch { return ''; } })();
+  if (!origin) return [];
+
+  // Cap context — only send url + name, not full element data
+  const screenList = screens
+    .slice(0, 80)
+    .map(s => {
+      try { return new URL(s.url).pathname + (s.name ? ` (${s.name})` : ''); } catch { return s.url; }
+    })
+    .join('\n');
+
+  const prompt = `You are analyzing the screen map of a web application to find structural coverage gaps.
+
+Discovered screens (${screens.length} total):
+${screenList}
+
+App URL: ${appUrl}
+
+Based on these screens and common patterns for this type of web application, identify screen categories that are likely present but missing. Focus on pages that would exist in a typical SaaS or web app but are not represented above.
+
+Respond with ONLY valid JSON, no markdown:
+{"gaps":[{"category":"User profile edit","urlPatterns":["/profile/edit","/account/profile"],"confidence":0.8,"rationale":"Profile view found but no edit page"},{"category":"Billing history","urlPatterns":["/settings/billing","/account/billing"],"confidence":0.7,"rationale":"Settings section found but no billing page"}]}`;
+
+  try {
+    const Anthropic = (await import('@anthropic-ai/sdk')).default;
+    const client = new Anthropic({ apiKey: llmCfg.apiKey });
+    const response = await client.messages.create({
+      model: llmCfg.model ?? 'claude-haiku-4-5-20251001',
+      max_tokens: 1024,
+      // @ts-ignore
+      system: [{ type: 'text', text: 'You are a web application coverage analyst. Respond with valid JSON only.', cache_control: { type: 'ephemeral' } }],
+      messages: [{ role: 'user', content: prompt }],
+    });
+
+    const text = (response.content[0] as any)?.text ?? '';
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) return [];
+    const parsed = JSON.parse(jsonMatch[0]);
+    const rawGaps: Array<{ category: string; urlPatterns: string[]; confidence: number; rationale: string }> =
+      parsed.gaps ?? [];
+
+    if (!Array.isArray(rawGaps) || rawGaps.length === 0) return [];
+    logger.info({ gaps: rawGaps.length }, '[P6] Gap analysis: LLM returned candidates');
+
+    // HEAD-validate each URL pattern, take the first 200
+    const results: GapCandidate[] = [];
+    for (const gap of rawGaps.slice(0, 15)) {
+      let confirmedUrl: string | null = null;
+      let headStatus: number | null = null;
+
+      for (const pattern of (gap.urlPatterns ?? []).slice(0, 4)) {
+        const fullUrl = pattern.startsWith('http') ? pattern : `${origin}${pattern.startsWith('/') ? '' : '/'}${pattern}`;
+        try {
+          const controller = new AbortController();
+          const timeout = setTimeout(() => controller.abort(), 6_000);
+          const res = await fetch(fullUrl, { method: 'HEAD', signal: controller.signal, redirect: 'follow' }).catch(() => null);
+          clearTimeout(timeout);
+          headStatus = res?.status ?? null;
+          if (res?.ok) { confirmedUrl = fullUrl; break; }
+        } catch { /* non-fatal */ }
+      }
+
+      results.push({ category: gap.category, urlPatterns: gap.urlPatterns, confidence: gap.confidence, rationale: gap.rationale, confirmedUrl, headStatus });
+      logger.info({ category: gap.category, confirmedUrl, headStatus }, '[P6] Gap candidate checked');
+    }
+
+    const confirmed = results.filter(r => r.confirmedUrl).length;
+    logger.info({ total: results.length, confirmed }, '[P6] Gap pass analysis complete');
+    return results;
+  } catch (err) {
+    logger.warn({ err: String(err) }, '[P6] Gap analysis failed — non-fatal');
+    return [];
+  }
+}

package/src/graphql-detector.ts

@@ -0,0 +1,129 @@
+/**
+ * GraphQL detection + introspection.
+ *
+ * During crawl, if a GraphQL endpoint is discovered (via network observer or
+ * known-URL heuristics), fire a minimal introspection query to get the schema.
+ * The schema is stored in the crawl artifact for use during test generation.
+ */
+
+export interface GqlType {
+  name: string;
+  kind: string;
+  fields?: Array<{ name: string; type: string }>;
+  inputFields?: Array<{ name: string; type: string }>;
+  enumValues?: string[];
+}
+
+export interface GqlSchema {
+  queryType?: string;
+  mutationType?: string;
+  subscriptionType?: string;
+  types: GqlType[];
+}
+
+export interface GqlIntrospectionResult {
+  endpoint: string;
+  schema: GqlSchema | null;
+  error?: string;
+  durationMs: number;
+}
+
+const INTROSPECTION_QUERY = `
+  query IntrospectionQuery {
+    __schema {
+      queryType { name }
+      mutationType { name }
+      subscriptionType { name }
+      types {
+        name
+        kind
+        fields(includeDeprecated: false) { name type { name kind ofType { name kind } } }
+        inputFields { name type { name kind ofType { name kind } } }
+        enumValues(includeDeprecated: false) { name }
+      }
+    }
+  }
+`;
+
+function flattenType(t: any): string {
+  if (!t) return 'unknown';
+  if (t.kind === 'NON_NULL' || t.kind === 'LIST') return flattenType(t.ofType);
+  return t.name ?? 'unknown';
+}
+
+function parseSchema(raw: any): GqlSchema {
+  const s = raw?.__schema ?? raw?.data?.__schema ?? raw;
+  const types: GqlType[] = (s?.types ?? [])
+    .filter((t: any) => !t.name?.startsWith('__'))
+    .map((t: any) => ({
+      name: t.name,
+      kind: t.kind,
+      fields: (t.fields ?? []).map((f: any) => ({ name: f.name, type: flattenType(f.type) })),
+      inputFields: (t.inputFields ?? []).map((f: any) => ({ name: f.name, type: flattenType(f.type) })),
+      enumValues: (t.enumValues ?? []).map((e: any) => e.name),
+    }));
+  return {
+    queryType: s?.queryType?.name,
+    mutationType: s?.mutationType?.name,
+    subscriptionType: s?.subscriptionType?.name,
+    types,
+  };
+}
+
+export async function introspectGraphQL(
+  endpoint: string,
+  opts: {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    cookies?: string;
+  } = {},
+): Promise<GqlIntrospectionResult> {
+  const { headers = {}, timeoutMs = 10_000, cookies } = opts;
+  const t0 = Date.now();
+  try {
+    const reqHeaders: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      ...headers,
+    };
+    if (cookies) reqHeaders['Cookie'] = cookies;
+
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers: reqHeaders,
+      body: JSON.stringify({ query: INTROSPECTION_QUERY }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+
+    if (!res.ok) {
+      return { endpoint, schema: null, error: `HTTP ${res.status}`, durationMs: Date.now() - t0 };
+    }
+
+    const json = await res.json();
+    if (json?.errors?.length) {
+      const msg = json.errors[0]?.message ?? 'introspection disabled';
+      return { endpoint, schema: null, error: msg, durationMs: Date.now() - t0 };
+    }
+
+    return { endpoint, schema: parseSchema(json?.data ?? json), durationMs: Date.now() - t0 };
+  } catch (e: any) {
+    return { endpoint, schema: null, error: e.message, durationMs: Date.now() - t0 };
+  }
+}
+
+/** Guess GraphQL endpoint URLs from a known app URL. */
+export function guessGraphQLEndpoints(appUrl: string): string[] {
+  try {
+    const u = new URL(appUrl);
+    const base = `${u.protocol}//${u.host}`;
+    return [
+      `${base}/graphql`,
+      `${base}/api/graphql`,
+      `${base}/v1/graphql`,
+      `${base}/gql`,
+      `${base}/query`,
+    ];
+  } catch {
+    return [];
+  }
+}