@houtini/seo-audit-console 0.2.3 → 0.4.3

package/dist/core/reconFetch.js

@@ -0,0 +1,49 @@
+import { extractPage } from './extract.js';
+export async function fetchOwnPage(url, hostForm = 'asis', timeoutMs = 20000) {
+    const host = new URL(url).hostname.replace(/^www\./, '');
+    const res = await fetch(url, {
+        headers: { 'user-agent': 'seo-audit-console recon (+https://github.com/houtini-ai/seo-audit)' },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const html = await res.text();
+    const ex = extractPage(html, url, host, { hostForm }, res.headers.get('x-robots-tag'));
+    const chunks = ex.bodyChunks ?? [];
+    const fulltextLower = chunks.map(c => `${c.heading} ${c.text}`).join(' ').toLowerCase();
+    // jsonLd is a JSON *string* (array of raw blocks) — parse ONCE, then each block (itself a
+    // JSON string or object) may carry an @graph. (Build lesson: don't iterate the raw string.)
+    const types = new Set();
+    let dateModified = null, datePublished = null;
+    try {
+        const blocks = ex.jsonLd ? JSON.parse(ex.jsonLd) : [];
+        for (const block of blocks) {
+            const obj = typeof block === 'string' ? JSON.parse(block) : block;
+            for (const node of (obj['@graph'] ?? [obj])) {
+                const t = node['@type'];
+                (Array.isArray(t) ? t : [t]).forEach((x) => x && types.add(x));
+                if (node.dateModified && !dateModified)
+                    dateModified = String(node.dateModified).slice(0, 10);
+                if (node.datePublished && !datePublished)
+                    datePublished = String(node.datePublished).slice(0, 10);
+            }
+        }
+    }
+    catch { /* malformed JSON-LD — leave types empty rather than throw */ }
+    return {
+        url,
+        status: res.status,
+        title: ex.title,
+        h1: ex.h1,
+        wordCount: ex.wordCount ?? fulltextLower.split(/\s+/).length,
+        headings: chunks.filter(c => c.heading).map(c => ({ level: c.level, heading: c.heading, chars: c.text.length })),
+        fulltextLower,
+        jsonLdTypes: [...types],
+        hasProductOrReview: types.has('Product') || types.has('Review') || types.has('AggregateRating'),
+        dateModified,
+        datePublished,
+    };
+}
+/** Which of these terms does the page text actually contain? Powers the coverage-gap probe. */
+export function coverageProbe(fulltextLower, terms) {
+    return terms.map(t => ({ term: t, present: fulltextLower.includes(t.toLowerCase()) }));
+}
+//# sourceMappingURL=reconFetch.js.map

package/dist/core/reconFetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconFetch.js","sourceRoot":"","sources":["../../src/core/reconFetch.ts"],"names":[],"mappings":"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"}

package/dist/core/reconResearch.d.ts

@@ -0,0 +1,42 @@
+import type { FirecrawlClient } from './FirecrawlClient.js';
+import type { SupadataClient } from './SupadataClient.js';
+/** User-agent modes for the free HTTP fetch. 'browser' mimics a real visit arriving from Google
+ * (referer + cross-site fetch metadata) — this is what gets past Reddit and the mid-tier.
+ * 'googlebot' spoofs Googlebot's UA (UA-gated sites only; strict-verified Cloudflare rejects it).
+ * Cloudflare *managed-challenge* sites (e.g. PCMag) reject every HTTP-only client regardless. */
+export type UaMode = 'browser' | 'googlebot';
+/**
+ * Route a competitor URL to the right fetcher by who owns the source:
+ *   YouTube/TikTok/X → Supadata (transcript)   — Firecrawl can't read video
+ *   Reddit           → its own .json endpoint   — Firecrawl hard-blocks Reddit
+ *   everything else  → Firecrawl (markdown, proxy:auto for bot-protected sites)
+ * Each returns a uniform shape so the recon packet is easy for the research session to diff.
+ */
+export interface CompetitorContent {
+    url: string;
+    kind: 'video' | 'reddit' | 'page';
+    title: string | null;
+    content: string;
+    cached: boolean;
+    error?: string;
+}
+/** Reddit serves clean JSON at url.json — title + selftext + top comments, no scraper needed.
+ * Needs the browser header profile (UA + Google referer) — a bot UA gets a 403. */
+export declare function fetchRedditJson(url: string, maxChars?: number, ua?: UaMode): Promise<{
+    title: string | null;
+    content: string;
+}>;
+/** Free HTTP fallback for pages Firecrawl refuses (its blocklist covers major publishers).
+ * Fetches with a browser-like UA and reuses our own extractor for clean main-content text. */
+export declare function fetchPlainPage(url: string, maxChars?: number, ua?: UaMode): Promise<{
+    title: string | null;
+    content: string;
+}>;
+export declare function fetchCompetitorContent(url: string, clients: {
+    firecrawl: FirecrawlClient | null;
+    supadata: SupadataClient | null;
+}, opts?: {
+    maxChars?: number;
+    ua?: UaMode;
+}): Promise<CompetitorContent>;
+//# sourceMappingURL=reconResearch.d.ts.map

package/dist/core/reconResearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconResearch.d.ts","sourceRoot":"","sources":["../../src/core/reconResearch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D;;;iGAGiG;AACjG,MAAM,MAAM,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC;AAmB7C;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD;mFACmF;AACnF,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAO,EAAE,EAAE,GAAE,MAAkB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAkB9I;AAED;8FAC8F;AAC9F,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAO,EAAE,EAAE,GAAE,MAAkB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ7I;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;CAAE,EAC/E,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,OAAO,CAAC,iBAAiB,CAAC,CA2B5B"}

package/dist/core/reconResearch.js

@@ -0,0 +1,101 @@
+import { Agent, fetch as ufetch } from 'undici';
+import { hostOf } from './serpRecon.js';
+import { extractPage } from './extract.js';
+const httpAgent = new Agent({ allowH2: true, connections: 6, keepAliveTimeout: 30_000 });
+const CHROME_UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
+const GOOGLEBOT_UA = 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Googlebot/2.1; +http://www.google.com/bot.html) Chrome/131.0.0.0 Safari/537.36';
+function browserHeaders(mode) {
+    if (mode === 'googlebot') {
+        return { 'user-agent': GOOGLEBOT_UA, 'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8', 'accept-encoding': 'gzip, deflate, br', 'from': 'googlebot(at)googlebot.com' };
+    }
+    return {
+        'user-agent': CHROME_UA,
+        'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
+        'accept-language': 'en-GB,en-US;q=0.9,en;q=0.8',
+        'accept-encoding': 'gzip, deflate, br',
+        'referer': 'https://www.google.com/',
+        'sec-ch-ua': '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
+        'sec-ch-ua-mobile': '?0', 'sec-ch-ua-platform': '"Windows"',
+        'sec-fetch-dest': 'document', 'sec-fetch-mode': 'navigate', 'sec-fetch-site': 'cross-site', 'sec-fetch-user': '?1',
+        'upgrade-insecure-requests': '1',
+    };
+}
+const isVideo = (host) => /youtube|youtu\.be|tiktok|twitter\.com|x\.com/.test(host);
+const isReddit = (host) => /reddit\.com/.test(host);
+/** Reddit serves clean JSON at url.json — title + selftext + top comments, no scraper needed.
+ * Needs the browser header profile (UA + Google referer) — a bot UA gets a 403. */
+export async function fetchRedditJson(url, maxChars = 4000, ua = 'browser') {
+    const jsonUrl = url.split('?')[0].replace(/\/$/, '') + '.json';
+    const res = await ufetch(jsonUrl, { headers: browserHeaders(ua), dispatcher: httpAgent, signal: AbortSignal.timeout(20000) });
+    if (!res.ok)
+        throw new Error(`Reddit .json ${res.status}`);
+    const data = await res.json();
+    const post = data?.[0]?.data?.children?.[0]?.data ?? {};
+    const comments = data?.[1]?.data?.children ?? [];
+    const parts = [];
+    if (post.title)
+        parts.push(`# ${post.title}`);
+    if (post.selftext)
+        parts.push(post.selftext);
+    const top = comments
+        .map(c => c?.data)
+        .filter(d => d && d.body && d.body !== '[deleted]')
+        .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+        .slice(0, 12)
+        .map(d => `- (${d.score ?? 0}) ${d.body}`);
+    if (top.length)
+        parts.push('## Top comments', ...top);
+    return { title: post.title ?? null, content: parts.join('\n\n').slice(0, maxChars) };
+}
+/** Free HTTP fallback for pages Firecrawl refuses (its blocklist covers major publishers).
+ * Fetches with a browser-like UA and reuses our own extractor for clean main-content text. */
+export async function fetchPlainPage(url, maxChars = 4000, ua = 'browser') {
+    const res = await ufetch(url, { headers: browserHeaders(ua), dispatcher: httpAgent, signal: AbortSignal.timeout(20000) });
+    if (!res.ok)
+        throw new Error(`plain fetch ${res.status}`);
+    const html = await res.text();
+    const host = new URL(url).hostname.replace(/^www\./, '');
+    const ex = extractPage(html, url, host, { hostForm: 'asis' }, null);
+    const text = (ex.bodyChunks ?? []).map(c => `${c.heading} ${c.text}`).join('\n').trim();
+    return { title: ex.title, content: text.slice(0, maxChars) };
+}
+export async function fetchCompetitorContent(url, clients, opts = {}) {
+    const host = hostOf(url);
+    const max = opts.maxChars ?? 4000;
+    const ua = opts.ua ?? 'browser';
+    try {
+        if (isVideo(host)) {
+            if (!clients.supadata)
+                return { url, kind: 'video', title: null, content: '', cached: false, error: 'SUPADATA_API_KEY not set — cannot transcribe video' };
+            const t = await clients.supadata.transcript(url, { maxChars: Math.max(max, 5000) });
+            return { url, kind: 'video', title: null, content: t.content, cached: t.cached };
+        }
+        if (isReddit(host)) {
+            // .json first (cleaner structured data); HTML fallback. Both need the browser profile.
+            try {
+                const r = await fetchRedditJson(url, max, ua);
+                return { url, kind: 'reddit', title: r.title, content: r.content, cached: false };
+            }
+            catch {
+                const r = await fetchPlainPage(url, max, ua);
+                return { url, kind: 'reddit', title: r.title, content: r.content, cached: false };
+            }
+        }
+        // Pages: Firecrawl first (cleaner, handles JS); fall back to the free browser-profile fetch
+        // for sites Firecrawl refuses ("we do not support this site") or when no key is set.
+        if (clients.firecrawl) {
+            try {
+                const s = await clients.firecrawl.scrape(url, { maxChars: max, proxy: 'auto' });
+                return { url, kind: 'page', title: s.title, content: s.markdown, cached: s.cached };
+            }
+            catch { /* fall through to the browser-profile fetch */ }
+        }
+        const p = await fetchPlainPage(url, max, ua);
+        return { url, kind: 'page', title: p.title, content: p.content, cached: false };
+    }
+    catch (e) {
+        const kind = isVideo(host) ? 'video' : isReddit(host) ? 'reddit' : 'page';
+        return { url, kind, title: null, content: '', cached: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+//# sourceMappingURL=reconResearch.js.map

package/dist/core/reconResearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconResearch.js","sourceRoot":"","sources":["../../src/core/reconResearch.ts"],"names":[],"mappings":"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"}

package/dist/core/serpFootprint.d.ts

@@ -0,0 +1,42 @@
+import type Database from 'better-sqlite3';
+/**
+ * SERP-feature footprint - "how much of my market is being eaten by SERP features?"
+ *
+ * Built from ONE cached DataForSEO Labs ranked_keywords pull (top-down, never SERP loops):
+ * each row carries keyword_data.serp_info.serp_item_types (the features PRESENT on that
+ * keyword's SERP) plus our rank. Aggregated volume-weighted, split by whether we rank
+ * page 1 on that keyword.
+ *
+ * Honesty: feature PRESENCE is deterministic (D - it's in the Labs index). Whether the
+ * feature helps or hurts US is a judgement proxy (N) - "we rank page 1" is the nearest
+ * cheap signal to ownership; true feature ownership needs per-keyword SERP calls.
+ */
+export interface FootprintRow {
+    feature: string;
+    label: string;
+    keywords: number;
+    volume: number;
+    volumeSharePct: number;
+    page1Keywords: number;
+    page1Volume: number;
+    page1SharePct: number;
+}
+export interface SerpFootprint {
+    target: string;
+    location: string | null;
+    sampleKeywords: number;
+    sampleVolume: number;
+    features: FootprintRow[];
+    fetchedAt?: string;
+}
+export interface SampleKeyword {
+    keyword: string;
+    position: number | null;
+    searchVolume: number | null;
+    serpFeatures: string[] | null;
+}
+export declare function computeSerpFootprint(target: string, location: string | null, sample: SampleKeyword[]): SerpFootprint;
+export declare function ensureFootprintTable(db: Database.Database): void;
+export declare function persistSerpFootprint(db: Database.Database, fp: SerpFootprint): void;
+export declare function latestSerpFootprint(db: Database.Database): SerpFootprint | null;
+//# sourceMappingURL=serpFootprint.d.ts.map

package/dist/core/serpFootprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serpFootprint.d.ts","sourceRoot":"","sources":["../../src/core/serpFootprint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgCD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC/B;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,aAAa,CA4BpH;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAYhE;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,aAAa,GAAG,IAAI,CAInF;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,aAAa,GAAG,IAAI,CAe/E"}

package/dist/core/serpFootprint.js

@@ -0,0 +1,99 @@
+const FEATURE_LABELS = {
+    ai_overview: 'AI Overview',
+    featured_snippet: 'Featured snippet',
+    people_also_ask: 'People also ask',
+    local_pack: 'Local pack',
+    shopping: 'Shopping',
+    popular_products: 'Popular products',
+    video: 'Video',
+    images: 'Images',
+    knowledge_graph: 'Knowledge panel',
+    top_stories: 'Top stories',
+    related_searches: 'Related searches',
+    people_also_search: 'People also search for',
+    organic: 'Organic results',
+    paid: 'Paid ads',
+    carousel: 'Carousel',
+    map: 'Map',
+    twitter: 'X (Twitter)',
+    discussions_and_forums: 'Discussions & forums',
+    short_videos: 'Short videos',
+    refine_products: 'Product refinements',
+    found_on_web: 'Found on the web',
+    perspectives: 'Perspectives',
+    product_considerations: 'Product considerations',
+    ai_mode: 'AI Mode',
+};
+// Ubiquitous furniture that says nothing about the market - excluded from the chart.
+const NOISE = new Set(['organic', 'related_searches', 'people_also_search', 'paid', 'images']);
+export function computeSerpFootprint(target, location, sample) {
+    const totVolume = sample.reduce((s, k) => s + (k.searchVolume ?? 0), 0);
+    const byFeature = new Map();
+    for (const k of sample) {
+        const vol = k.searchVolume ?? 0;
+        const page1 = k.position != null && k.position <= 10;
+        for (const f of k.serpFeatures ?? []) {
+            const b = byFeature.get(f) ?? { keywords: 0, volume: 0, p1k: 0, p1v: 0 };
+            b.keywords++;
+            b.volume += vol;
+            if (page1) {
+                b.p1k++;
+                b.p1v += vol;
+            }
+            byFeature.set(f, b);
+        }
+    }
+    const features = [...byFeature.entries()]
+        .filter(([f]) => !NOISE.has(f))
+        .map(([f, b]) => ({
+        feature: f,
+        label: FEATURE_LABELS[f] ?? f.replace(/_/g, ' '),
+        keywords: b.keywords,
+        volume: Math.round(b.volume),
+        volumeSharePct: totVolume ? Math.round((b.volume / totVolume) * 1000) / 10 : 0,
+        page1Keywords: b.p1k,
+        page1Volume: Math.round(b.p1v),
+        page1SharePct: b.volume ? Math.round((b.p1v / b.volume) * 1000) / 10 : 0,
+    }))
+        .sort((a, b) => b.volume - a.volume)
+        .slice(0, 12);
+    return { target, location, sampleKeywords: sample.length, sampleVolume: Math.round(totVolume), features };
+}
+export function ensureFootprintTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS serp_footprint (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      target TEXT NOT NULL,
+      location TEXT,
+      sample_keywords INTEGER NOT NULL,
+      sample_volume REAL NOT NULL,
+      features TEXT NOT NULL,          -- JSON FootprintRow[]
+      fetched_at TEXT DEFAULT (datetime('now'))
+    );
+  `);
+}
+export function persistSerpFootprint(db, fp) {
+    ensureFootprintTable(db);
+    db.prepare(`INSERT INTO serp_footprint (target, location, sample_keywords, sample_volume, features) VALUES (?, ?, ?, ?, ?)`)
+        .run(fp.target, fp.location, fp.sampleKeywords, fp.sampleVolume, JSON.stringify(fp.features));
+}
+export function latestSerpFootprint(db) {
+    ensureFootprintTable(db);
+    const row = db.prepare(`SELECT target, location, sample_keywords, sample_volume, features, fetched_at FROM serp_footprint ORDER BY id DESC LIMIT 1`).get();
+    if (!row)
+        return null;
+    try {
+        return {
+            target: row.target,
+            location: row.location,
+            sampleKeywords: row.sample_keywords,
+            sampleVolume: row.sample_volume,
+            features: JSON.parse(row.features),
+            fetchedAt: row.fetched_at,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=serpFootprint.js.map

package/dist/core/serpFootprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serpFootprint.js","sourceRoot":"","sources":["../../src/core/serpFootprint.ts"],"names":[],"mappings":"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"}

package/dist/core/serpRecon.d.ts

@@ -0,0 +1,46 @@
+import type { DfsResponse } from './DataForSeoClient.js';
+/**
+ * Parse a DataForSEO SERP-advanced response into the fields content recon needs:
+ * where WE actually rank in organic, whether the AI Overview cites us and who it does
+ * cite, and how much of the SERP is video/product (format signals). This is the single
+ * fetch that powers the organic-rank x AIO-citation verdict matrix.
+ */
+export interface SerpReconResult {
+    itemTypes: string[];
+    ourOrganicRank: number | null;
+    aioPresent: boolean;
+    aioCitesUs: boolean;
+    aioAsync: boolean;
+    aioReferences: {
+        rank: number | null;
+        domain: string;
+        url: string;
+        title: string;
+    }[];
+    videoPresent: boolean;
+    organicAbove: {
+        rank: number;
+        domain: string;
+        url: string;
+        title: string;
+    }[];
+    videoItems: {
+        url: string;
+        title: string;
+        source: string;
+    }[];
+}
+/** Registrable-ish host: lowercase, strip scheme/path/www. Good enough to match a domain field. */
+export declare function hostOf(s: string | undefined | null): string;
+export declare function parseSerpForRecon(resp: DfsResponse, ownDomain: string): SerpReconResult;
+/**
+ * The deterministic verdict from organic rank x AIO citation (Richard's rule):
+ * strong organic but NOT in the AIO = a data-accuracy/freshness problem — Google ranks
+ * us but won't quote us.
+ */
+export type ReconVerdict = 'defend-and-deepen' | 'accuracy-or-freshness' | 'consolidate-weak-page' | 'competitive-gap';
+export declare function reconVerdict(r: SerpReconResult): {
+    verdict: ReconVerdict;
+    note: string;
+};
+//# sourceMappingURL=serpRecon.d.ts.map

package/dist/core/serpRecon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serpRecon.d.ts","sourceRoot":"","sources":["../../src/core/serpRecon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrF,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7E,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9D;AAED,mGAAmG;AACnG,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAG3D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CA2CvF;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,uBAAuB,GAAG,uBAAuB,GAAG,iBAAiB,CAAC;AAEvH,wBAAgB,YAAY,CAAC,CAAC,EAAE,eAAe,GAAG;IAAE,OAAO,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAkBxF"}

package/dist/core/serpRecon.js

@@ -0,0 +1,71 @@
+/** Registrable-ish host: lowercase, strip scheme/path/www. Good enough to match a domain field. */
+export function hostOf(s) {
+    if (!s)
+        return '';
+    return String(s).replace(/^https?:\/\//i, '').replace(/\/.*$/, '').replace(/^www\./i, '').toLowerCase().trim();
+}
+export function parseSerpForRecon(resp, ownDomain) {
+    const own = hostOf(ownDomain);
+    const result = resp.tasks?.[0]?.result?.[0] ?? {};
+    const items = result.items ?? [];
+    const itemTypes = result.item_types ?? [...new Set(items.map(i => i.type))];
+    let ourOrganicRank = null;
+    const organic = [];
+    let aioPresent = false, aioCitesUs = false, aioAsync = false, videoPresent = false;
+    const aioReferences = [];
+    const videoItems = [];
+    for (const it of items) {
+        const t = it.type;
+        if (t === 'organic') {
+            const domain = hostOf(it.domain || it.url);
+            const rank = Number(it.rank_group) || organic.length + 1;
+            organic.push({ rank, domain, url: it.url ?? '', title: it.title ?? '' });
+            if (own && domain === own && ourOrganicRank == null)
+                ourOrganicRank = rank;
+        }
+        else if (t === 'ai_overview') {
+            aioPresent = true;
+            aioAsync = !!it.asynchronous_ai_overview;
+            const refs = it.references ?? [];
+            let i = 0;
+            for (const ref of refs) {
+                const domain = hostOf(ref.domain || ref.url);
+                aioReferences.push({ rank: Number(ref.rank_absolute) || ++i, domain, url: ref.url ?? '', title: ref.title ?? '' });
+                if (own && domain === own)
+                    aioCitesUs = true;
+            }
+        }
+        else if (t === 'video' || t === 'short_videos') {
+            videoPresent = true;
+            for (const v of it.items ?? []) {
+                if (v?.url)
+                    videoItems.push({ url: v.url, title: v.title ?? '', source: hostOf(v.url) });
+            }
+        }
+    }
+    // Organic ranked above us (the ones actually beating us); if we're absent, the whole top block.
+    const organicAbove = ourOrganicRank == null
+        ? organic.slice(0, 8)
+        : organic.filter(o => o.rank < ourOrganicRank);
+    return { itemTypes, ourOrganicRank, aioPresent, aioCitesUs, aioAsync, aioReferences, videoPresent, organicAbove, videoItems };
+}
+export function reconVerdict(r) {
+    const strongOrganic = r.ourOrganicRank != null && r.ourOrganicRank <= 5;
+    const shape = r.videoPresent ? ' The SERP carries a video pack, so some click loss is format, not content.' : '';
+    if (!r.aioPresent) {
+        return strongOrganic
+            ? { verdict: 'defend-and-deepen', note: `No AI Overview on this SERP; you rank organic #${r.ourOrganicRank}. Defend and deepen.${shape}` }
+            : { verdict: 'competitive-gap', note: `No AI Overview; you rank organic ${r.ourOrganicRank ?? 'outside top results'}. Close the competitive gap.${shape}` };
+    }
+    if (strongOrganic && r.aioCitesUs) {
+        return { verdict: 'defend-and-deepen', note: `You rank organic #${r.ourOrganicRank} and the AI Overview already cites you. Deepen to become the primary source.${shape}` };
+    }
+    if (strongOrganic && !r.aioCitesUs) {
+        return { verdict: 'accuracy-or-freshness', note: `You rank organic #${r.ourOrganicRank} but the AI Overview does NOT cite you — a data-accuracy or freshness signal. Make the facts current, correct and marked up so they are liftable.${shape}` };
+    }
+    if (!strongOrganic && r.aioCitesUs) {
+        return { verdict: 'consolidate-weak-page', note: `The AI Overview cites you but your organic rank is weak (${r.ourOrganicRank ?? 'absent'}) — you have a quotable nugget on an under-powered page; consolidate and strengthen it.${shape}` };
+    }
+    return { verdict: 'competitive-gap', note: `Not cited in the AI Overview and organic rank is ${r.ourOrganicRank ?? 'absent'} — full coverage gap; run the deep competitor diff.${shape}` };
+}
+//# sourceMappingURL=serpRecon.js.map

package/dist/core/serpRecon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serpRecon.js","sourceRoot":"","sources":["../../src/core/serpRecon.ts"],"names":[],"mappings":"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"}

package/dist/core/webServer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Local dashboard webserver — the "Phase 2" delivery surface. Serves the built dashboard
+ * UI at http://127.0.0.1:PORT with live data from the property SQLite DBs, so the report
+ * lives in a real browser tab: no MCP-App host cache, no iframe sandbox, native file
+ * downloads, and a property switcher. Localhost-only by design (binds 127.0.0.1).
+ */
+/** Named server-side handlers the web UI may invoke via POST /api/call (allowlist). */
+export type WebCallHandlers = Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>>;
+export interface WebServerOptions {
+    dataDir: () => string;
+    /** Returns the built dashboard.html template (read per-request so rebuilds show without restart). */
+    uiHtml: () => string;
+    call: WebCallHandlers;
+    port?: number;
+}
+/** Enumerate properties that have a local DB (property_meta.site_url is the source of truth). */
+export declare function listLocalProperties(dataDir: string): {
+    siteUrl: string;
+    file: string;
+}[];
+export declare function startDashboardServer(opts: WebServerOptions): Promise<{
+    url: string;
+    port: number;
+}>;
+export declare function stopDashboardServer(): Promise<boolean>;
+export declare function dashboardServerUrl(): string | null;
+//# sourceMappingURL=webServer.d.ts.map

package/dist/core/webServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webServer.d.ts","sourceRoot":"","sources":["../../src/core/webServer.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AAEH,uFAAuF;AACvF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAElH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,MAAM,CAAC;IACtB,qGAAqG;IACrG,MAAM,EAAE,MAAM,MAAM,CAAC;IACrB,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAgBD,iGAAiG;AACjG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAaxF;AA4BD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA2EzG;AAED,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC,CAM5D;AAED,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAElD"}