katman-mcp 0.1.0

package/dist/tools/visibility/render.js

@@ -0,0 +1,295 @@
+import { mdTable, truncate } from "../../util.js";
+import { sameSite } from "./analyze.js";
+import { money, moneyRange } from "./estimate.js";
+import { engineOf, vendorOf } from "./models.js";
+import { ratio } from "./summary.js";
+export const PROXY_NOTE = "API answers are a proxy for the consumer apps. Confirm key questions with katman_manual_check.";
+export const SAMPLE_NOTE = "One run is a small sample: the same question can get a different answer in the next session. Named and cited are the reliable signals; who is ranked first changes a lot between sessions.";
+export function pct(k, n) {
+    if (!n)
+        return "—";
+    return `${k}/${n} (${Math.round((100 * k) / n)}%)`;
+}
+export function pts(before, beforeN, after, afterN) {
+    if (!beforeN || !afterN)
+        return "—";
+    const d = Math.round(100 * (ratio(after, afterN) - ratio(before, beforeN)));
+    return d === 0 ? "±0 pts" : `${d > 0 ? "+" : ""}${d} pts`;
+}
+export function shortFamily(f) {
+    if (f.startsWith("ChatGPT"))
+        return "ChatGPT";
+    if (/exa search/i.test(f))
+        return "Gemini*";
+    return f;
+}
+export function searchLabel(spec) {
+    const engine = engineOf(spec);
+    if (engine === "none")
+        return "off";
+    if (vendorOf(spec.id) === "perplexity")
+        return "built-in (Perplexity index)";
+    if (engine === "exa")
+        return "Exa (proxy index)";
+    const v = vendorOf(spec.id);
+    return v === "google" ? "native (Google grounding)" : "native";
+}
+const utc = (iso) => iso.slice(0, 16).replace("T", " ") + " UTC";
+export function minutes(answers, concurrency) {
+    const waves = Math.ceil(answers / Math.max(1, concurrency));
+    const lo = Math.max(1, Math.round((waves * 15) / 60));
+    const hi = Math.max(lo + 1, Math.round((waves * 45) / 60));
+    return `${lo}–${hi} min`;
+}
+export function renderDryRun(v) {
+    const e = v.estimate;
+    const L = [];
+    L.push("# AI visibility run: dry run (nothing was spent)", "");
+    if (v.activeRun)
+        L.push(`> ${v.activeRun}`, "");
+    if (v.lastRun) {
+        const r = v.lastRun;
+        L.push(`Last API run: ${utc(r.ts)} · named in ${pct(r.mentioned, r.answered)} unbranded answers · cited in ${pct(r.cited, r.citedOf)}${r.cost ? ` · cost ${money(r.cost)}` : ""} (details: .katman/measurements.md).`, "");
+    }
+    const qDesc = `${v.questions.length} questions (${v.scoredCount} unbranded + ${v.diagnosticCount} diagnostic${v.brandedCount ? `, ${v.brandedCount} naming the brand` : ""})`;
+    L.push(`**${v.brand}** (${v.domain}) · ${qDesc} × ${v.models.length} assistant${v.models.length === 1 ? "" : "s"}${v.samples > 1 ? ` × ${v.samples} samples` : ""} = **${e.answers} answers**, live web search, temperature ${v.temperature}.`, "");
+    const rows = e.rows.map((r) => [
+        r.spec.family, r.spec.id, searchLabel(r.spec), r.answers, moneyRange(r.perAnswer), moneyRange(r.total) + (r.lastActual ? ` (last run: ${money(r.lastActual)}/answer)` : ""),
+    ]);
+    if (e.judge)
+        rows.push(["judge (extracts recommended products)", e.judge.model, "—", e.judge.calls, moneyRange(e.judge.perCall), moneyRange(e.judge.total)]);
+    if (e.followUps)
+        rows.push(["follow-up \"which pages did you use?\"", "same models", "same", `≤ ${e.followUps.maxCalls}`, "—", moneyRange(e.followUps.total)]);
+    rows.push(["**total**", "", "", `**${e.answers}**`, "", `**${moneyRange(e.total)} (expected ≈ ${money(e.total.expected)})**`]);
+    L.push(mdTable(["assistant", "OpenRouter model", "web search", "answers", "per answer", "total"], rows), "");
+    const fits = e.total.expected <= v.maxCost;
+    L.push(`**Cost cap (max_cost_usd): ${money(v.maxCost)}.** ${fits
+        ? e.total.high <= v.maxCost
+            ? "The whole estimate fits under the cap."
+            : "The expected cost fits; if answers run long, the run stops starting new calls at the cap and marks the rest as skipped (never silently)."
+        : "The expected cost is above the cap, so a real run with these settings refuses to start."}`);
+    if (!fits || e.total.high > v.maxCost) {
+        const opts = [`raise the cap (\`max_cost_usd: ${Math.max(v.maxCost, Math.ceil(e.total.high * 2) / 2)}\`)`];
+        for (const a of v.alternatives)
+            opts.push(`${a.label} ≈ ${money(a.expected)} (max ${money(a.high)}): \`${a.call}\``);
+        opts.push("fewer questions (`question_ids`)");
+        L.push(`Options: ${opts.join("; ")}.`);
+    }
+    const capArg = fits ? v.maxCost : Math.max(v.maxCost, Math.ceil(e.total.high * 2) / 2);
+    L.push("", `Time: about ${minutes(e.answers, v.concurrency)} (${v.concurrency} calls at a time). If your MCP client times out, the run keeps going and saves its results; or run \`npx -y katman-mcp check --root . --yes --max-cost ${capArg}\` in a terminal.`, "");
+    if (v.key.present) {
+        const limit = v.key.error ? `could not read key info (${v.key.error})`
+            : v.key.limitRemaining === null || v.key.limitRemaining === undefined
+                ? "this key has no spending limit; check the account balance at https://openrouter.ai/settings/credits"
+                : `key limit remaining: ${money(v.key.limitRemaining)}${v.key.limitRemaining < e.total.high ? " (less than the high estimate: the run may stop early with 402)" : ""}`;
+        L.push(`OpenRouter key: found in ${v.key.source} · ${limit}.`);
+    }
+    else {
+        L.push("OpenRouter key: **not set**. See below.");
+    }
+    L.push(`Prices: ${v.catalog.source === "live" ? "live OpenRouter catalog" : v.catalog.source === "cache" ? "OpenRouter catalog (cached)" : v.catalog.source === "stale-cache" ? "an older cached catalog" : "built-in prices (verified 2026-09-30)"}${v.catalog.fetchedAt ? `, fetched ${utc(v.catalog.fetchedAt)}` : ""}.`, "", "How the estimate works: native web search puts the search results into the prompt, so an answer costs far more than the question itself. Ranges come from measured native-search runs (Sep 2026):");
+    const bases = [...new Set(e.rows.map((r) => r.basis))];
+    for (const b of bases)
+        L.push(`- ${b}`);
+    L.push("After your first run, estimates use your own measured cost per answer.", "");
+    if (v.notes.length) {
+        L.push("Notes:");
+        for (const n of v.notes)
+            L.push(`- ${n}`);
+        L.push("");
+    }
+    L.push(PROXY_NOTE, "");
+    if (v.keyHelp)
+        L.push(v.keyHelp, "");
+    if (!v.key.present) {
+        L.push(`**Next:** tell the user what a run costs (about ${money(e.total.expected)}, at most ${money(Math.max(e.total.high, e.total.expected))}) and that it needs their own OpenRouter key (steps above). Until then, \`katman_manual_check\` costs nothing (no API credits).`);
+        return L.join("\n");
+    }
+    L.push(`**Next:** ask the user: "This asks ${e.answers} AI answers and costs about ${money(e.total.expected)} (at most ${money(Math.min(capArg, Math.max(e.total.high, e.total.expected)))}) from your OpenRouter credit. Run it?" Only after a clear yes, call \`katman_visibility_run\` with \`dry_run: false\`${capArg !== 2 ? ` and \`max_cost_usd: ${capArg}\`` : ""} (same other arguments). No-cost alternative: \`katman_manual_check\`.`);
+    return L.join("\n");
+}
+function cell(answers, diagnostic) {
+    if (!answers.length)
+        return "";
+    const ok = answers.filter((a) => !a.error);
+    if (!ok.length)
+        return /^(skipped|not run)/i.test(answers[0].error ?? "") ? "skip" : "err";
+    if (answers.length > 1) {
+        const m = ok.filter((a) => a.mentioned).length;
+        const c = ok.filter((a) => a.cited).length;
+        return `${m}/${ok.length} named${c ? ` · ${c} cited` : ""}`;
+    }
+    const a = ok[0];
+    if (diagnostic) {
+        const id = a.identityCorrect === true ? "correct" : a.identityCorrect === false ? "wrong" : "unclear";
+        return `${a.mentioned ? "✓" : "✗"} ${id}${a.cited ? " · cited" : ""}`;
+    }
+    if (!a.mentioned)
+        return a.cited ? "✗ · cited" : "✗";
+    return `✓${a.rank ? ` #${a.rank}` : ""}${a.cited ? " · cited" : ""}`;
+}
+export function renderGrid(run, questions) {
+    const families = [...new Set(run.models.map((m) => m.family))];
+    const qIds = [...new Set(run.answers.map((a) => a.questionId))];
+    const byId = new Map(questions.map((q) => [q.id, q]));
+    const rows = qIds.map((id) => {
+        const any = run.answers.find((a) => a.questionId === id);
+        const diagnostic = any.questionType === "diagnostic";
+        const q = byId.get(id)?.text ?? any.question;
+        return [
+            id,
+            truncate(q, 60) + (diagnostic ? " (diagnostic)" : ""),
+            ...families.map((f) => cell(run.answers.filter((a) => a.questionId === id && a.family === f), diagnostic)),
+        ];
+    });
+    return mdTable(["#", "question", ...families.map(shortFamily)], rows);
+}
+function avgRank(answers) {
+    const r = answers.map((a) => a.rank).filter((x) => typeof x === "number");
+    return r.length ? (r.reduce((s, x) => s + x, 0) / r.length).toFixed(1) : "—";
+}
+export function renderRunReport(v) {
+    const { run, extras: x } = v;
+    const s = run.summary;
+    const L = [];
+    const brand = run.brand;
+    L.push(`# AI visibility run: ${brand} (${run.domain}) · ${utc(run.ts)}`, "");
+    const total = (run.totalCostUsd ?? 0);
+    const answered = run.answers.filter((a) => !a.error).length;
+    L.push(`${answered} of ${run.answers.length} answers received from ${run.models.length} assistant${run.models.length === 1 ? "" : "s"} (OpenRouter API, live web search, temperature ${run.temperature ?? "n/a"}) · spent ${money(total)} (answers ${money(v.costs.answers)}${v.costs.followUps ? `, follow-ups ${money(v.costs.followUps)}` : ""}${v.costs.judge ? `, judge ${money(v.costs.judge)}` : ""}).`);
+    if (v.stopped)
+        L.push("", `> **Incomplete run:** ${v.stopped} The answers that did come back are saved and counted below; the missing ones are marked "skip".`);
+    L.push("");
+    const citedPart = x.citationDenominator ? `cited in ${pct(x.citedCount, x.citationDenominator)}` : "no assistant returned sources";
+    const totals = Object.values(s.byFamily).reduce((t, b) => ({ mentioned: t.mentioned + b.mentioned, first: t.first + b.recommendedFirst }), { mentioned: 0, first: 0 });
+    L.push(`**Named in ${pct(totals.mentioned, s.answered)} unbranded answers · ${citedPart}.** These are the headline numbers. Recommended first: ${pct(totals.first, s.answered)}, a secondary signal (the first-named brand changes between sessions).`, "");
+    L.push("## By assistant", "");
+    const famRows = run.models.map((m) => {
+        const b = s.byFamily[m.family] ?? { answered: 0, mentioned: 0, recommendedFirst: 0, cited: 0 };
+        const answersF = run.answers.filter((a) => a.family === m.family && !a.error);
+        const returned = [...new Set(answersF.map((a) => a.model))].join(", ") || m.id;
+        const d = v.diff?.byFamily[m.family];
+        const searched = answersF.filter((a) => a.searched === true).length;
+        return [
+            m.family,
+            returned,
+            answersF.length ? `${searched}/${answersF.length}` : "—",
+            pct(b.mentioned, b.answered),
+            x.citationBlind.includes(m.family) ? "no sources returned" : pct(b.cited, b.answered),
+            pct(b.recommendedFirst, b.answered),
+            avgRank(answersF.filter((a) => v.branded.has(a.questionId) === false && a.questionType !== "diagnostic")),
+            ...(v.diff ? [d ? pts(d.before.mentioned, d.before.answered, d.after.mentioned, d.after.answered) : "new"] : []),
+        ];
+    });
+    L.push(mdTable(["assistant", "model (as answered)", "searched the web", "named", "cited", "recommended first", "avg rank", ...(v.diff ? [`Δ named vs ${v.diff.previousTs.slice(0, 10)}`] : [])], famRows), "");
+    if (v.multiLanguage) {
+        L.push("## By language", "");
+        L.push(mdTable(["language", "answers", "named", "cited", "recommended first"], Object.entries(x.byLanguage).map(([lang, b]) => [lang, b.answered, pct(b.mentioned, b.answered), pct(b.cited, b.answered), pct(b.recommendedFirst, b.answered)])), "");
+    }
+    L.push("## Per question", "", renderGrid(run, v.questions), "");
+    L.push(`✓ named (#n = its position among the recommended products) · cited = a page of ${run.domain} was among the sources · ✗ not named · err = the call failed · skip = not run.`, "");
+    if (x.stability.length) {
+        const unstable = x.stability.filter((st) => st.mentioned > 0 && st.mentioned < st.samples);
+        L.push(`Stability across samples: ${x.stability.filter((st) => st.mentioned === st.samples).length} question × assistant pairs named every time, ${unstable.length} only sometimes, ${x.stability.filter((st) => st.mentioned === 0).length} never.`, "");
+    }
+    if (v.diff) {
+        const d = v.diff;
+        L.push(`## Changes since ${d.previousTs.slice(0, 10)} (run ${d.previousId})`, "");
+        if (!d.pairs)
+            L.push("No question × assistant pair was answered in both runs, so there is nothing to compare.", "");
+        else {
+            L.push(`Compared on the ${d.pairs} question × assistant pairs answered in both runs${!d.sameModels || !d.sameQuestions ? " (the model panel or question set changed since then; only matching pairs count)" : ""}.`, `- Named: ${pct(d.before.mentioned, d.before.answered)} → ${pct(d.after.mentioned, d.after.answered)} (${pts(d.before.mentioned, d.before.answered, d.after.mentioned, d.after.answered)})`, `- Cited: ${pct(d.before.cited, d.before.answered)} → ${pct(d.after.cited, d.after.answered)} · recommended first: ${pct(d.before.recommendedFirst, d.before.answered)} → ${pct(d.after.recommendedFirst, d.after.answered)}`);
+            if (d.gained.length)
+                L.push(`- Newly named: ${d.gained.slice(0, 12).map((g) => `${g.questionId} × ${shortFamily(g.family)}`).join(", ")}`);
+            if (d.lost.length)
+                L.push(`- No longer named: ${d.lost.slice(0, 12).map((g) => `${g.questionId} × ${shortFamily(g.family)}`).join(", ")}`);
+            L.push("");
+        }
+    }
+    L.push("## Recommended instead of you (top competitors)", "");
+    if (s.topCompetitors.length) {
+        const fresh = new Set(x.newCompetitors);
+        L.push(mdTable(["product", "answers", "in research?"], s.topCompetitors.map((c) => [c.name, c.count, fresh.has(c.name) ? "new: add it with its own page as source and today's date" : "yes"])), "");
+    }
+    else
+        L.push("No other products were named.", "");
+    L.push("## Sources the assistants used = your off-site targets", "");
+    if (s.topCitedDomains.length) {
+        L.push(mdTable(["domain", "answers citing it"], s.topCitedDomains.map((d) => [d.domain, d.count])), "");
+        L.push("Get your brand onto these pages: independent lists, reviews, directories, forums (book ch. 14). Pitch the authors with facts and disclose any paid placement.", "");
+    }
+    else
+        L.push("No sources were returned.", "");
+    const diag = run.answers.filter((a) => a.questionType === "diagnostic" && !a.error);
+    if (diag.length) {
+        L.push("## Diagnostics (T1/T2, not counted in the rates)", "");
+        L.push(mdTable(["question", "assistant", "knows you", "describes you correctly", "cited"], diag.map((a) => [truncate(a.question, 50), shortFamily(a.family), a.mentioned ? "yes" : "no", a.identityCorrect === true ? "yes" : a.identityCorrect === false ? "no (confused)" : "unclear", a.cited ? "yes" : "no"])), "");
+        if (diag.some((a) => a.identityCorrect === false))
+            L.push("An assistant confuses you with something else: make the one sentence and the \"not X\" note identical on the homepage, llms.txt and schema (katman_prompt P4/P5).", "");
+    }
+    L.push("## Notes", "");
+    for (const w of v.warnings)
+        L.push(`- ${w}`);
+    L.push(`- ${SAMPLE_NOTE} This run scored ${s.answered} answers.`, `- Re-run the same questions on **${v.nextRun}** (+14 days) and compare.`, `- ${PROXY_NOTE}`, `- Saved: ${v.runFile} and .katman/measurements.md.`);
+    return L.join("\n");
+}
+// ---------------------------------------------------------------------------
+// measurements.md
+function citedPages(a, own) {
+    const pages = a.citations.filter((c) => own.some((d) => sameSite(c.domain, d))).map((c) => {
+        try {
+            const u = new URL(c.url);
+            return u.pathname === "/" ? u.hostname : u.pathname;
+        }
+        catch {
+            return c.url;
+        }
+    });
+    return pages.length ? [...new Set(pages)].slice(0, 3).join(", ") : "—";
+}
+function runSource(r) {
+    const first = r.answers[0];
+    if (first?.source === "manual")
+        return `manual · ${first.model}`;
+    return "API (OpenRouter)";
+}
+export function renderMeasurements(runs, o) {
+    const sorted = [...runs].sort((a, b) => b.ts.localeCompare(a.ts));
+    const L = [];
+    L.push(`# AI visibility measurements: ${o.brand} (${o.domain})`, "");
+    L.push(`Regenerated by Katman on ${o.now.toISOString().slice(0, 10)} from .katman/runs/ (edits here are overwritten). Method (book ch. 7 and 15): the same questions every 14 days, logged out, web search on; record who was named, the position, who was recommended and which of your pages was cited.`, "", `${SAMPLE_NOTE} ${PROXY_NOTE}`, "", "## Runs", "");
+    if (!sorted.length) {
+        L.push("No runs yet. Start with `katman_visibility_run` (dry run first) or `katman_manual_check` (no API cost).");
+        return L.join("\n") + "\n";
+    }
+    L.push(mdTable(["date", "source", "assistants", "scored answers", "named", "recommended first", "cited", "cost"], sorted.map((r) => {
+        const s = r.summary;
+        const answered = s?.answered ?? 0;
+        return [
+            utc(r.ts),
+            runSource(r),
+            [...new Set(r.models.map((m) => shortFamily(m.family)))].join(", "),
+            answered,
+            pct(Math.round((s?.mentionRate ?? 0) * answered), answered),
+            pct(Math.round((s?.recommendedFirstRate ?? 0) * answered), answered),
+            `${Math.round((s?.citationRate ?? 0) * 100)}%`,
+            r.totalCostUsd ? money(r.totalCostUsd) : r.answers[0]?.source === "manual" ? "free" : "—",
+        ];
+    })), "");
+    const detail = sorted.slice(0, o.detailRuns ?? 8);
+    for (const r of detail) {
+        L.push(`## ${utc(r.ts)} · ${runSource(r)} · ${r.id}`, "");
+        L.push(mdTable(["date", "question", "assistant", "mentioned", "rank", "who was recommended", "cited page"], r.answers.map((a) => [
+            a.ts.slice(0, 10),
+            truncate(a.question, 70) + (a.questionType === "diagnostic" ? " (diagnostic)" : ""),
+            shortFamily(a.family) + (a.sample && a.sample > 1 ? ` (sample ${a.sample})` : ""),
+            a.error ? truncate(a.error, 40) : a.mentioned ? "yes" : "no",
+            a.rank ?? "—",
+            a.namedProducts.slice(0, 4).join(", ") || "—",
+            citedPages(a, o.ownDomains),
+        ])), "");
+    }
+    if (sorted.length > detail.length)
+        L.push(`Older runs: see .katman/runs/ (${sorted.length - detail.length} more).`, "");
+    return L.join("\n");
+}