katman-mcp 0.1.0

package/dist/tools/visibility/analyze.js

@@ -0,0 +1,463 @@
+import { domainOf, truncate } from "../../util.js";
+// ---------------------------------------------------------------------------
+// Folding: case- and diacritics-insensitive text with a map back to the original offsets.
+const EXTRA_FOLD = {
+    ı: "i", ß: "ss", æ: "ae", Æ: "ae", ø: "o", Ø: "o", œ: "oe", Œ: "oe", đ: "d", Đ: "d", ł: "l", Ł: "l", þ: "th", Þ: "th",
+    "’": "'", "‘": "'", "‐": "-", "‑": "-", "–": "-", "—": "-",
+};
+function foldChar(ch) {
+    const x = EXTRA_FOLD[ch];
+    if (x !== undefined)
+        return x;
+    if (ch.charCodeAt(0) < 128)
+        return ch.toLowerCase();
+    return ch.normalize("NFKD").replace(/\p{M}+/gu, "").toLowerCase();
+}
+export function foldWithMap(s) {
+    let text = "";
+    const map = [];
+    let i = 0;
+    for (const ch of s) {
+        const f = foldChar(ch);
+        for (let k = 0; k < f.length; k++)
+            map.push(i);
+        text += f;
+        i += ch.length;
+    }
+    map.push(i);
+    return { text, map };
+}
+export function fold(s) {
+    return foldWithMap(s).text;
+}
+/** Comparison key: folded words joined by single spaces ("Çözüm-AI" → "cozum ai"). */
+export function foldKey(s) {
+    return fold(s).split(/[^\p{L}\p{N}]+/u).filter(Boolean).join(" ");
+}
+// ---------------------------------------------------------------------------
+// Domains
+/** Two-level public suffixes common for our users' markets. */
+const TWO_LEVEL = new Set([
+    "co.uk", "org.uk", "ac.uk", "me.uk", "com.tr", "net.tr", "org.tr", "gen.tr", "web.tr", "biz.tr", "info.tr", "av.tr", "k12.tr",
+    "com.au", "net.au", "org.au", "co.nz", "co.za", "com.br", "com.mx", "co.jp", "ne.jp", "or.jp", "co.kr", "co.in", "net.in",
+    "com.cn", "com.hk", "com.sg", "com.ar", "com.co", "com.ua", "com.pl", "co.il", "com.my", "com.ph", "com.vn", "co.id", "co.th",
+    "com.eg", "com.sa", "com.es", "com.pt", "co.at", "or.at",
+]);
+/** Hosting domains where the site is the subdomain (the label must not become "vercel", "github"…). */
+const HOSTING_SUFFIXES = [
+    "vercel.app", "netlify.app", "github.io", "gitlab.io", "pages.dev", "workers.dev", "web.app", "firebaseapp.com", "herokuapp.com",
+    "onrender.com", "fly.dev", "lovable.app", "replit.app", "repl.co", "glitch.me", "surge.sh", "framer.website", "framer.app",
+    "webflow.io", "wixsite.com", "carrd.co", "notion.site", "super.site", "azurewebsites.net", "amplifyapp.com", "up.railway.app",
+    "railway.app", "deno.dev", "appspot.com", "bolt.host", "netlify.com", "vercel.com",
+];
+/** Platforms whose domain says nothing about a competitor listed there (github.com/foo, apps.apple.com/…). */
+const PLATFORM_DOMAINS = new Set([
+    "github.com", "gitlab.com", "apple.com", "google.com", "microsoft.com", "producthunt.com", "youtube.com", "medium.com",
+    "substack.com", "notion.so", "notion.site", "chromewebstore.google.com", "linkedin.com", "facebook.com", "instagram.com",
+    "x.com", "twitter.com", "tiktok.com", "reddit.com", "npmjs.com", "pypi.org", "huggingface.co", "wordpress.org", "shopify.com",
+]);
+export function normalizeHost(input) {
+    if (!input)
+        return "";
+    const s = input.trim();
+    if (!s)
+        return "";
+    return domainOf(/^[a-z]+:\/\//i.test(s) ? s : `https://${s}`).replace(/\.$/, "");
+}
+export function registrableDomain(host) {
+    const h = normalizeHost(host);
+    for (const suf of HOSTING_SUFFIXES) {
+        if (h.endsWith("." + suf)) {
+            const sub = h.slice(0, -suf.length - 1).split(".").pop();
+            return sub ? `${sub}.${suf}` : suf;
+        }
+    }
+    const parts = h.split(".").filter(Boolean);
+    if (parts.length <= 2)
+        return parts.join(".");
+    const last2 = parts.slice(-2).join(".");
+    return TWO_LEVEL.has(last2) ? parts.slice(-3).join(".") : last2;
+}
+/** "example.shop" → "example"; "app.acme.com.tr" → "acme"; "myapp.vercel.app" → "myapp". */
+export function domainLabel(host) {
+    const reg = registrableDomain(host);
+    return reg.split(".")[0] || undefined;
+}
+export function sameSite(domain, own) {
+    if (!domain || !own)
+        return false;
+    return domain === own || domain.endsWith("." + own);
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const B_BEFORE = "(?<![\\p{L}\\p{N}])";
+const B_AFTER = "(?![\\p{L}\\p{N}])";
+/** Whole-word phrase on folded text; words may be joined by space, hyphen, dot, underscore, +, &, / or nothing ("Acme Books" = "acme-books" = "AcmeBooks", "C++ Builder"). Not by commas. */
+function phrasePattern(term) {
+    const tokens = fold(term).split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    if (!tokens.length)
+        return undefined;
+    return new RegExp(B_BEFORE + tokens.map(escapeRe).join("[\\s\\-_.·+&/]{0,4}") + B_AFTER, "gu");
+}
+/** "katman.pro" also matches "www.katman.pro" and "app.katman.pro", not "notkatman.pro" or "katman.pro.evil.com". */
+function domainPattern(domain) {
+    return new RegExp("(?<![\\p{L}\\p{N}-])" + escapeRe(fold(domain)) + "(?![\\p{L}\\p{N}-]|\\.[\\p{L}\\p{N}])", "gu");
+}
+const looksLikeDomain = (s) => /^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(s.trim());
+export function buildEntity(name, o = {}) {
+    const patterns = [];
+    const seen = new Set();
+    const addPhrase = (term, kind) => {
+        const key = foldKey(term);
+        if (!key || seen.has(key))
+            return;
+        const re = phrasePattern(term);
+        if (!re)
+            return;
+        seen.add(key);
+        patterns.push({ kind, term: key, re });
+    };
+    const domains = [];
+    const addDomain = (d, withLabel) => {
+        const host = normalizeHost(d);
+        if (!host || !host.includes(".") || domains.includes(host))
+            return;
+        if (o.platformCheck && PLATFORM_DOMAINS.has(registrableDomain(host)))
+            return;
+        domains.push(host);
+        patterns.push({ kind: "domain", term: host, re: domainPattern(host) });
+        const label = domainLabel(host);
+        if (withLabel && label && label.length >= 4)
+            addPhrase(label, "label");
+    };
+    addPhrase(name, "name");
+    for (const a of o.alternateNames ?? []) {
+        if (typeof a !== "string" || fold(a).replace(/[^\p{L}\p{N}]/gu, "").length < 3)
+            continue;
+        if (looksLikeDomain(a))
+            addDomain(a, false);
+        else
+            addPhrase(a, "alt");
+    }
+    const d = o.domain || (o.url ? domainOf(o.url) : "");
+    if (d)
+        addDomain(d, true);
+    return { name, patterns, domains };
+}
+export function findHits(text, e) {
+    const f = typeof text === "string" ? foldWithMap(text) : text;
+    const hits = [];
+    for (const p of e.patterns) {
+        p.re.lastIndex = 0;
+        for (let m = p.re.exec(f.text); m; m = p.re.exec(f.text)) {
+            hits.push({ index: f.map[m.index] ?? 0, kind: p.kind });
+            if (m[0].length === 0)
+                p.re.lastIndex++;
+        }
+    }
+    return hits.sort((a, b) => a.index - b.index);
+}
+export function buildContext(r) {
+    const domain = normalizeHost(r.site?.domain || r.site?.url || "");
+    const brand = buildEntity(r.brand.name.trim(), { alternateNames: r.brand.alternateNames, domain });
+    const own = [domain, ...(r.site?.previewUrls ?? []).map((u) => normalizeHost(u))].filter(Boolean);
+    const brandKey = foldKey(r.brand.name);
+    const competitors = (r.competitors ?? [])
+        .filter((c) => c && typeof c.name === "string" && c.name.trim() && foldKey(c.name) !== brandKey)
+        .map((c) => buildEntity(c.name.trim(), { url: c.url, platformCheck: true }));
+    return { brand, competitors, ownDomains: [...new Set(own)] };
+}
+export function mentions(ctx, text) {
+    return findHits(text, ctx.brand).length > 0;
+}
+/** Canonical research competitor name for a product string, if it is one of them. */
+export function canonicalCompetitor(ctx, name) {
+    const f = foldWithMap(name);
+    return ctx.competitors.find((c) => findHits(f, c).length > 0)?.name;
+}
+// ---------------------------------------------------------------------------
+// Links and citations
+const TRAILING = /[.,;:!?'"»”’>*_\]]+$/u;
+function trimUrl(raw) {
+    let s = raw.trim();
+    for (;;) {
+        const before = s;
+        s = s.replace(TRAILING, "");
+        // Keep ")" only when balanced, e.g. https://en.wikipedia.org/wiki/Foo_(bar)
+        while (s.endsWith(")") && (s.match(/\(/g)?.length ?? 0) < (s.match(/\)/g)?.length ?? 0))
+            s = s.slice(0, -1);
+        if (s === before)
+            return s;
+    }
+}
+export function normalizeUrl(raw) {
+    let s = trimUrl(raw);
+    if (/^www\./i.test(s))
+        s = `https://${s}`;
+    let u;
+    try {
+        u = new URL(s);
+    }
+    catch {
+        return undefined;
+    }
+    if (!/^https?:$/.test(u.protocol) || !u.hostname.includes("."))
+        return undefined;
+    u.hash = "";
+    for (const k of [...u.searchParams.keys()]) {
+        if (/^utm_/i.test(k) || /^(gclid|fbclid|srsltid|mc_cid|mc_eid)$/i.test(k))
+            u.searchParams.delete(k);
+    }
+    const out = u.toString();
+    return u.pathname === "/" && !u.search ? out.replace(/\/$/, "") : out;
+}
+/** Start of a markdown link whose target is an http(s) URL; the URL itself is read by readMdUrl. */
+const MD_LINK_START = /\[([^\]\n]{0,300})\]\(\s*<?(?=https?:\/\/)/giu;
+/**
+ * Read a markdown link target starting at `start`, balancing parentheses so URLs like
+ * https://en.wikipedia.org/wiki/Mercury_(planet) survive intact. Returns the URL and the index after
+ * the link's closing ")" (optional <…> and "title" allowed), or undefined if it isn't a well-formed link.
+ */
+function readMdUrl(text, start) {
+    let i = start;
+    let depth = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === " " || ch === "\n" || ch === "\t" || ch === "\r" || ch === "<" || ch === ">")
+            break;
+        if (ch === "(")
+            depth++;
+        else if (ch === ")") {
+            if (depth === 0)
+                break;
+            depth--;
+        }
+        i++;
+    }
+    const url = text.slice(start, i);
+    let j = i;
+    if (text[j] === ">")
+        j++;
+    const rest = /^\s*(?:"[^"\n]*"\s*)?\)/.exec(text.slice(j, j + 400));
+    if (!url || !rest)
+        return undefined;
+    return { url, end: j + rest[0].length };
+}
+const BARE_URL = /(?:https?:\/\/|\bwww\.)[^\s<>"'`[\]{}|\\^]+/giu;
+/** Markdown links and bare URLs written in the answer text. */
+export function extractLinks(text) {
+    const out = [];
+    const spans = [];
+    for (const m of text.matchAll(MD_LINK_START)) {
+        const i = m.index ?? 0;
+        const link = readMdUrl(text, i + m[0].length);
+        if (!link)
+            continue;
+        spans.push([i, link.end]);
+        const title = m[1].replace(/[*_`]/g, "").trim();
+        out.push({ url: link.url, title: title.length > 2 && !/^\d+$/.test(title) ? title : undefined });
+    }
+    for (const m of text.matchAll(BARE_URL)) {
+        const i = m.index ?? 0;
+        if (spans.some(([a, b]) => i >= a && i < b))
+            continue;
+        out.push({ url: m[0] });
+    }
+    return out;
+}
+export function toCitations(items, limit = 40) {
+    const byKey = new Map();
+    for (const it of items) {
+        const url = normalizeUrl(it.url);
+        if (!url)
+            continue;
+        const key = url.toLowerCase().replace(/\/$/, "");
+        const existing = byKey.get(key);
+        if (existing) {
+            if (!existing.title && it.title)
+                existing.title = truncate(it.title, 200);
+            continue;
+        }
+        if (byKey.size >= limit)
+            continue;
+        const c = { url, domain: domainOf(url) };
+        if (it.title)
+            c.title = truncate(it.title, 200);
+        byKey.set(key, c);
+    }
+    return [...byKey.values()];
+}
+// ---------------------------------------------------------------------------
+// Heuristic product list (fallback when the judge is off or fails)
+const STOP_ITEMS = new Set([
+    "pros", "cons", "pricing", "price", "prices", "cost", "features", "feature", "key features", "best for", "ideal for", "good for",
+    "why", "how", "how it works", "what it does", "note", "notes", "tip", "tips", "summary", "conclusion", "overview", "verdict",
+    "bottom line", "limitations", "drawbacks", "downsides", "advantages", "disadvantages", "example", "examples", "use case",
+    "use cases", "steps", "step", "option", "options", "alternatives", "recommendation", "recommendations", "free", "paid",
+    "free plan", "website", "link", "links", "source", "sources", "reference", "references", "faq", "yes", "no", "quick answer",
+    "short answer", "my recommendation", "final thoughts", "comparison", "table", "tool", "tools", "platform", "name",
+    "artilar", "eksiler", "fiyat", "fiyatlandirma", "ozellikler", "neden", "nasil", "ipucu", "ozet", "sonuc", "avantajlar",
+    "dezavantajlar", "ornek", "kimler icin", "ucretsiz", "ucretli", "kaynaklar", "kaynak", "adim", "arac", "araclar", "oneri",
+    "evet", "hayir", "diger secenekler", "secenekler", "other options",
+].map((s) => foldKey(s)));
+function nameFromItem(raw) {
+    let t = raw.trim().replace(/^[^\p{L}\p{N}*_[]+/u, "");
+    const bold = t.match(/^(?:\*\*|__)(.+?)(?:\*\*|__)/);
+    const link = t.match(/^\[([^\]]+)\]\([^)]*\)/);
+    if (bold)
+        t = bold[1];
+    else if (link)
+        t = link[1];
+    else {
+        const m = t.match(/^(.{2,60}?)(?:\s[-–—]\s|:\s|\s\(|,\s|\s\|)/);
+        if (m)
+            t = m[1];
+        else if (t.length > 45)
+            return undefined;
+    }
+    t = t
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+        .replace(/[*_`#]/g, "")
+        .replace(/^\d{1,2}[.)]\s*/, "")
+        .replace(/[:.,;–—-]+$/u, "")
+        .trim();
+    if (!t || t.length > 60 || !/\p{L}/u.test(t))
+        return undefined;
+    const words = t.split(/\s+/);
+    if (words.length > 6)
+        return undefined;
+    if (words.length >= 4 && /^\p{Ll}/u.test(t))
+        return undefined; // sentence fragment, not a name
+    if (STOP_ITEMS.has(foldKey(t)) || /^(step|adim|option|secenek)\s*\d+$/i.test(foldKey(t)))
+        return undefined;
+    return t;
+}
+/** Candidate product names in order of appearance: known entities (first mention) + list items, headings, bold line starts, table first cells. */
+export function heuristicProducts(text, known) {
+    const folded = foldWithMap(text);
+    const cands = [];
+    for (const e of known) {
+        const h = findHits(folded, e)[0];
+        if (h)
+            cands.push({ pos: h.index, name: e.name });
+    }
+    const lines = text.split("\n");
+    let offset = 0;
+    for (let li = 0; li < lines.length; li++) {
+        const line = lines[li];
+        const pos = offset;
+        offset += line.length + 1;
+        let raw;
+        const table = line.match(/^\s*\|(.+)\|\s*$/);
+        if (table) {
+            const cells = table[1].split("|").map((c) => c.trim());
+            if (cells.every((c) => /^:?-{2,}:?$/.test(c)))
+                continue;
+            if (/^\s*\|?\s*:?-{2,}/.test(lines[li + 1] ?? ""))
+                continue; // header row
+            raw = cells[0];
+        }
+        else {
+            const item = line.match(/^( ?)(?:#{1,6}\s*)?(?:\d{1,2}[.)]|[-*•+])\s+(.+)$/);
+            const heading = line.match(/^#{1,6}\s+(.+)$/);
+            const bold = line.match(/^ ?(\*\*.+?\*\*.*)$/);
+            if (!item && heading) {
+                // A heading counts only when it is itself a name ("### Acme", "### 2. **Example Pro**"), not a sentence.
+                const h = heading[1].replace(/^\d{1,2}[.)]\s*/, "").trim();
+                const b = h.match(/^\*\*(.+?)\*\*/);
+                raw = b ? b[1] : h.split(/\s+/).length <= 4 && !/[,.?!;]/.test(h.replace(/:$/, "")) ? h : undefined;
+            }
+            else
+                raw = item?.[2] ?? bold?.[1];
+        }
+        if (!raw)
+            continue;
+        const name = nameFromItem(raw);
+        if (!name)
+            continue;
+        const f = foldWithMap(name);
+        const knownName = known.find((e) => findHits(f, e).length > 0)?.name;
+        cands.push({ pos, name: knownName ?? name });
+    }
+    cands.sort((a, b) => a.pos - b.pos);
+    return dedupeNames(cands.map((c) => c.name)).slice(0, 15);
+}
+/** Dedupe by folded key; "Acme" and "Acme AI" count as one (the first spelling wins). */
+export function dedupeNames(names) {
+    const out = [];
+    const keys = [];
+    for (const n of names) {
+        const k = foldKey(n);
+        if (!k)
+            continue;
+        if (keys.some((x) => x === k || k.startsWith(x + " ") || x.startsWith(k + " ")))
+            continue;
+        keys.push(k);
+        out.push(n.trim());
+    }
+    return out;
+}
+export function excerptAround(text, index, max = 600) {
+    const clean = (s) => s.replace(/\s+/g, " ").trim();
+    if (index === undefined)
+        return truncate(clean(text), max);
+    const start = Math.max(0, index - Math.floor(max / 3));
+    const end = Math.min(text.length, start + max);
+    return (start > 0 ? "…" : "") + clean(text.slice(start, end)) + (end < text.length ? "…" : "");
+}
+export function cleanProducts(list) {
+    const names = list
+        .filter((x) => typeof x === "string")
+        .map((x) => x.replace(/\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/[*_`]/g, "").trim())
+        .filter((x) => x.length > 0 && x.length <= 80 && /[\p{L}\p{N}]/u.test(x));
+    return dedupeNames(names).slice(0, 20);
+}
+export function analyzeAnswer(ctx, input) {
+    const folded = foldWithMap(input.text);
+    const hits = findHits(folded, ctx.brand);
+    const mentionKinds = [...new Set(hits.map((h) => h.kind))];
+    const j = input.judge ?? null;
+    let mentioned = hits.length > 0;
+    let vetoed = false;
+    // A bare-name match can be an ordinary word ("katman" = "layer" in Turkish). Only then may the judge overrule presence.
+    if (mentioned && j && j.brand_mentioned === false && mentionKinds.every((k) => k === "name" || k === "label")) {
+        mentioned = false;
+        vetoed = true;
+    }
+    const competitorsNamed = ctx.competitors
+        .map((e) => ({ e, h: findHits(folded, e)[0] }))
+        .filter((x) => !!x.h)
+        .sort((a, b) => a.h.index - b.h.index)
+        .map((x) => x.e.name);
+    const method = j ? "judge" : "heuristic";
+    const namedProducts = j ? cleanProducts(j.products) : heuristicProducts(input.text, [ctx.brand, ...ctx.competitors]);
+    let rank = null;
+    if (mentioned) {
+        const idx = namedProducts.findIndex((p) => findHits(p, ctx.brand).length > 0);
+        if (idx >= 0)
+            rank = idx + 1;
+        else if (j && typeof j.brand_rank === "number" && j.brand_rank >= 1 && j.brand_rank <= namedProducts.length)
+            rank = j.brand_rank;
+    }
+    const citations = toCitations([
+        ...(input.sources ?? []),
+        ...extractLinks(input.text),
+        ...(input.followUpSources ?? []).map((s) => ({ url: s.url, title: s.title ? `(follow-up) ${s.title}` : "(follow-up)" })),
+    ]);
+    const cited = citations.some((c) => ctx.ownDomains.some((d) => sameSite(c.domain, d)));
+    const result = {
+        mentioned,
+        mentionKinds,
+        vetoed,
+        recommendedFirst: rank === 1,
+        rank,
+        cited,
+        namedProducts,
+        competitorsNamed,
+        citations,
+        answerExcerpt: excerptAround(input.text, mentioned ? hits[0]?.index : undefined),
+        method,
+    };
+    if (input.questionType === "diagnostic")
+        result.identityCorrect = j ? j.identity_correct : null;
+    return result;
+}

package/dist/tools/visibility/cli.js

@@ -0,0 +1,86 @@
+// CLI: `katman-mcp check` (dry run unless --yes; used by the GitHub Actions workflow) and
+// `katman-mcp models` (default assistant models with live OpenRouter prices).
+import path from "node:path";
+import { parseArgs } from "../../cli.js";
+import { mdTable } from "../../util.js";
+import { money, moneyRange, perAnswer } from "./estimate.js";
+import { MODELS_VERIFIED_ON, profileFor, resolveJudge, resolvePanel } from "./models.js";
+import { isInCatalog, loadCatalog, priceOf, searchUnitPrice } from "./openrouter.js";
+import { searchLabel } from "./render.js";
+import { visibilityRun } from "./run.js";
+const list = (v) => typeof v === "string" ? v.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+const num = (v) => (typeof v === "string" && v.trim() && Number.isFinite(Number(v)) ? Number(v) : undefined);
+const on = (v) => v === true || v === "true" || v === "1";
+async function check(args) {
+    const { flags } = parseArgs(args);
+    if (on(flags.help) || on(flags.h)) {
+        console.log(help.join("\n"));
+        return 0;
+    }
+    const root = path.resolve(typeof flags.root === "string" ? flags.root : process.cwd());
+    const runArgs = {
+        dry_run: !(on(flags.yes) || on(flags.y)),
+        models: list(flags.models),
+        question_ids: list(flags.questions),
+        max_cost_usd: num(flags["max-cost"]),
+        samples: num(flags.samples),
+        concurrency: num(flags.concurrency),
+        temperature: num(flags.temperature),
+        judge: on(flags["no-judge"]) ? false : undefined,
+        follow_up_sources: on(flags["follow-up"]) || undefined,
+        allow_google_grounding: on(flags["google-grounding"]) || undefined,
+    };
+    const out = await visibilityRun(root, runArgs, {
+        onProgress: (done, total, message) => process.stderr.write(`[${done}/${total}] ${message}\n`),
+    });
+    console.log(out.text);
+    const status = out.structured?.status;
+    if (out.isError)
+        return status === "refused_over_cap" || status === "key_limit_too_low" ? 2 : 1;
+    return status === "partial" ? 3 : 0;
+}
+async function models() {
+    const catalog = await loadCatalog(undefined, {});
+    const isAvailable = (s) => isInCatalog(catalog, s);
+    const L = [
+        `# Katman visibility models (defaults verified ${MODELS_VERIFIED_ON}; prices ${catalog.source === "live" ? "live from openrouter.ai" : "built-in"})`,
+        "",
+    ];
+    if (catalog.warning)
+        L.push(catalog.warning, "");
+    for (const preset of ["full", "economy", "probe"]) {
+        const panel = resolvePanel({ input: preset, isAvailable });
+        L.push(`## ${preset}${preset === "full" ? " (default)" : ""}`, "");
+        L.push(mdTable(["assistant", "OpenRouter model", "web search", "$/M in / out", "per search", "≈ per answer"], panel.models.map((m) => {
+            const p = priceOf(catalog, m.id);
+            return [
+                m.family,
+                m.id + (isAvailable(m.id) === false ? " (not in catalog)" : ""),
+                searchLabel(m),
+                `${(p.prompt * 1e6).toFixed(2)} / ${(p.completion * 1e6).toFixed(2)}`,
+                money(searchUnitPrice(m, p)),
+                moneyRange(perAnswer(p, profileFor(m).profile, searchUnitPrice(m, p))),
+            ];
+        })), "");
+        for (const n of panel.notes)
+            L.push(`- ${n}`);
+        if (panel.notes.length)
+            L.push("");
+    }
+    const judge = resolveJudge(undefined, isAvailable);
+    const jp = priceOf(catalog, judge);
+    L.push(`Judge (extracts the recommended products): ${judge}, $${(jp.prompt * 1e6).toFixed(2)} / $${(jp.completion * 1e6).toFixed(2)} per M tokens.`, "");
+    L.push("Per-answer ranges include the search results that native search adds to the prompt (measured Sep 2026). Run `katman-mcp check --root .` for a full estimate of your question set.", 'Override in .katman/config.json: {"models": [{"id": "openai/gpt-6-luna", "family": "ChatGPT (OpenAI)", "search": "native"}], "judgeModel": "openai/gpt-6-luna", "temperature": 0.7}');
+    console.log(L.join("\n"));
+    return 0;
+}
+export const commands = {
+    check,
+    models: () => models(),
+};
+export const help = [
+    "  katman-mcp check [--root .] [--yes] [--max-cost 3] [--models a,b]",
+    "                             AI visibility run via OpenRouter (OPENROUTER_API_KEY); dry run unless --yes",
+    "                             also: --questions q1,q2 --samples 3 --concurrency 4 --no-judge --follow-up --google-grounding",
+    "  katman-mcp models          default assistant models (full / economy / probe) with live OpenRouter prices",
+];

package/dist/tools/visibility/estimate.js

@@ -0,0 +1,105 @@
+export const ZERO = { low: 0, high: 0, expected: 0 };
+export function addRange(a, b) {
+    return { low: a.low + b.low, high: a.high + b.high, expected: a.expected + b.expected };
+}
+export function scaleRange(a, k) {
+    return { low: a.low * k, high: a.high * k, expected: a.expected * k };
+}
+const mid = (a) => (a[0] + a[1]) / 2;
+/** Cost of one answer from token and search ranges (USD). */
+export function perAnswer(price, p, searchUnit) {
+    const at = (inT, outT, s) => inT * price.prompt + outT * price.completion + s * searchUnit + price.request;
+    return {
+        low: at(p.inputTokens[0], p.outputTokens[0], p.searches[0]),
+        high: at(p.inputTokens[1], p.outputTokens[1], p.searches[1]),
+        expected: at(mid(p.inputTokens), mid(p.outputTokens), mid(p.searches)),
+    };
+}
+/** Judge call: extraction prompt + the answer in, a short JSON verdict out. */
+export const JUDGE_PROFILE = {
+    inputTokens: [700, 3200], outputTokens: [60, 400], searches: [0, 0],
+    basis: "extraction prompt (~500 tokens) + answer (≤ ~2.5k tokens), JSON out",
+};
+/** Follow-up turn: the conversation so far plus "which pages did you use?", searching again. */
+export function followUpProfile(p) {
+    return {
+        inputTokens: [p.inputTokens[0] + 600, p.inputTokens[1] + 2600],
+        outputTokens: [150, 800],
+        searches: p.searches,
+        basis: "conversation so far + the follow-up question",
+    };
+}
+export function estimateRun(i) {
+    const samples = Math.max(1, Math.floor(i.samples));
+    const answersPerModel = i.questions * samples;
+    const rows = i.models.map((m) => {
+        let pa = perAnswer(m.price, m.profile, m.searchUnit);
+        if (m.lastActual !== undefined && m.lastActual > 0) {
+            // Calibrate on what this model actually cost last time, keep the profile's spread.
+            pa = { low: Math.min(pa.low, m.lastActual * 0.6), high: Math.max(pa.high, m.lastActual * 1.6), expected: m.lastActual };
+        }
+        return {
+            spec: m.spec,
+            answers: answersPerModel,
+            perAnswer: pa,
+            total: scaleRange(pa, answersPerModel),
+            price: m.price,
+            lastActual: m.lastActual,
+            basis: m.profile.basis,
+        };
+    });
+    const answers = answersPerModel * i.models.length;
+    let total = rows.reduce((acc, r) => addRange(acc, r.total), ZERO);
+    let judge;
+    if (i.judge) {
+        const perCall = perAnswer(i.judge.price, JUDGE_PROFILE, 0);
+        judge = { model: i.judge.model, calls: answers, perCall, total: scaleRange(perCall, answers) };
+        total = addRange(total, judge.total);
+    }
+    let followUps;
+    if (i.followUps) {
+        // Only answers that don't name the brand get a follow-up: assume 50–100 % (expected 80 %) of scored answers.
+        const scored = i.scoredQuestions * samples;
+        let t = ZERO;
+        i.models.forEach((m, k) => {
+            const f = perAnswer(m.price, followUpProfile(m.profile), m.searchUnit);
+            rows[k].followUpPerCall = f;
+            t = addRange(t, { low: f.low * scored * 0.5, high: f.high * scored, expected: f.expected * scored * 0.8 });
+        });
+        followUps = { maxCalls: scored * i.models.length, total: t };
+        total = addRange(total, t);
+    }
+    return { rows, answers, judge, followUps, total };
+}
+/** Reservation for one (question, model) task in the live cost guard. */
+export function taskCost(row, est, followUp) {
+    let expected = row.perAnswer.expected;
+    let high = row.perAnswer.high;
+    if (est.judge) {
+        expected += est.judge.perCall.expected;
+        high += est.judge.perCall.high;
+    }
+    if (followUp && row.followUpPerCall) {
+        expected += row.followUpPerCall.expected * 0.8;
+        high += row.followUpPerCall.high;
+    }
+    return { expected, high };
+}
+export function money(n) {
+    if (!Number.isFinite(n))
+        return "?";
+    if (n === 0)
+        return "$0";
+    if (n < 0.01)
+        return `$${n.toFixed(4)}`;
+    if (n < 1)
+        return `$${n.toFixed(3)}`;
+    return `$${n.toFixed(2)}`;
+}
+export function moneyRange(r) {
+    return `${money(r.low)}–${money(r.high)}`;
+}
+/** Round a cap suggestion up to the next 50 cents. */
+export function suggestCap(high) {
+    return Math.max(0.5, Math.ceil(high * 2) / 2);
+}