@relvehq/agent-ready 0.0.0-stage → 0.3.0

package/dist/proof/audit.js

@@ -0,0 +1,253 @@
+"use strict";
+// Proof: the free checker. "How agent-ready is this site?" for any URL,
+// installed or not. Read-only GETs, the way an agent would ask:
+//
+//   page        the HTML loads
+//   accept      Accept: text/markdown gets Markdown                  (25)
+//   md-url      <page>.md gets Markdown                               (15)
+//   llms        /llms.txt exists and looks like one                   (15)
+//   robots      robots.txt lets the AI answer bots in                 (15)
+//   sitemap     /sitemap.xml lists pages                              (10)
+//   json-ld     the page has structured data                          (10)
+//   vary        Markdown is sent with Vary: Accept                     (5)
+//   canonical   the page (or its Markdown) names a canonical URL       (5)
+//
+// Score = points earned / 100 (a warning earns half). Plus the token count of
+// the HTML vs the Markdown an agent got, or could get (when `convert` is
+// passed: the CLI passes the package's converter). EDGE-SAFE unless `convert`
+// is Node-only (the caller decides).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditSite = auditSite;
+exports.blockedBots = blockedBots;
+exports.formatAudit = formatAudit;
+const enrich_1 = require("../core/enrich");
+const sitemap_1 = require("../core/sitemap");
+const bots_1 = require("./bots");
+const UA = "agent-ready-check/0.1 (+https://www.npmjs.com/package/@relvehq/agent-ready)";
+async function auditSite(rawUrl, opts = {}) {
+    const f = opts.fetch ?? fetch;
+    const url = normalizeUrl(rawUrl);
+    const report = {
+        url,
+        checkedAt: (opts.now ?? (() => new Date()))().toISOString(),
+        ok: false,
+        error: null,
+        score: 0,
+        grade: "F",
+        checks: [],
+        tokens: { html: null, served: null, converted: null },
+    };
+    const get = (u, accept) => timed(f, u, accept, opts.timeoutMs ?? 10000);
+    const u = new URL(url);
+    const origin = u.origin;
+    const add = (c) => report.checks.push(c);
+    // The page itself.
+    const page = await get(url, "text/html,application/xhtml+xml;q=0.9,*/*;q=0.8");
+    if (!page || !page.ok) {
+        report.error = page ? `The page answered HTTP ${page.status}.` : "The page could not be reached.";
+        add({ id: "page", label: "Page loads", status: "fail", points: 0, detail: report.error, fix: "Check the URL; the checker needs the page to load." });
+        return finish(report);
+    }
+    report.ok = true;
+    report.tokens.html = (0, enrich_1.estimateTokens)(page.body);
+    add({ id: "page", label: "Page loads", status: "pass", points: 0, detail: `HTTP ${page.status}, ${fmt(report.tokens.html)} tokens of HTML.`, fix: "" });
+    // Markdown by Accept, and by .md URL.
+    const viaAccept = await get(url, "text/markdown, text/html;q=0.5");
+    const acceptMd = !!viaAccept?.ok && isMarkdown(viaAccept.type);
+    add({
+        id: "accept",
+        label: "Answers Accept: text/markdown",
+        status: acceptMd ? "pass" : "fail",
+        points: 25,
+        detail: acceptMd ? `Markdown, ${fmt((0, enrich_1.estimateTokens)(viaAccept.body))} tokens.` : `Got ${viaAccept ? viaAccept.type || "no content type" : "no answer"}.`,
+        fix: acceptMd ? "" : "Serve Markdown when an agent asks for it: `npx agent-ready init`.",
+    });
+    const mdUrl = origin + (u.pathname === "/" ? "/index.md" : u.pathname.replace(/\/+$/, "") + ".md");
+    const viaMd = await get(mdUrl, "text/markdown, text/plain;q=0.9, */*;q=0.1");
+    const suffixMd = !!viaMd?.ok && isMarkdown(viaMd.type);
+    add({
+        id: "md-url",
+        label: "Has a .md version",
+        status: suffixMd ? "pass" : "fail",
+        points: 15,
+        detail: suffixMd ? `${mdUrl} answers with Markdown.` : `${mdUrl} answered ${viaMd ? `HTTP ${viaMd.status}` : "nothing"}.`,
+        fix: suffixMd ? "" : "Serve <page>.md as Markdown (the package does this).",
+    });
+    const md = acceptMd ? viaAccept : suffixMd ? viaMd : null;
+    if (md)
+        report.tokens.served = (0, enrich_1.estimateTokens)(md.body);
+    // llms.txt
+    const llms = await get(origin + "/llms.txt", "text/plain, text/markdown;q=0.9, */*;q=0.1");
+    const llmsOk = !!llms?.ok && /^\s*#\s+\S/.test(llms.body) && !/^\s*<(!doctype|html)/i.test(llms.body);
+    const llmsLinks = llmsOk ? (llms.body.match(/\]\(https?:\/\/[^)]+\)/g) ?? []).length : 0;
+    add({
+        id: "llms",
+        label: "Publishes /llms.txt",
+        status: llmsOk ? (llmsLinks ? "pass" : "warn") : "fail",
+        points: 15,
+        detail: llmsOk ? `${llmsLinks} links listed.` : llms?.ok ? "/llms.txt exists but isn't an llms.txt file." : "No /llms.txt.",
+        fix: llmsOk && llmsLinks ? "" : "Publish /llms.txt (the package builds one from your sitemap).",
+    });
+    // robots.txt
+    const robots = await get(origin + "/robots.txt", "text/plain");
+    const blocked = robots?.ok ? blockedBots(robots.body, bots_1.ANSWER_BOT_TOKENS) : [];
+    add({
+        id: "robots",
+        label: "Lets AI answer bots in",
+        status: !robots?.ok ? "warn" : blocked.length ? "fail" : "pass",
+        points: 15,
+        detail: !robots?.ok ? "No robots.txt (everything is allowed by default)." : blocked.length ? `Blocked: ${blocked.join(", ")}.` : `Allowed: ${bots_1.ANSWER_BOT_TOKENS.join(", ")}.`,
+        fix: blocked.length ? "Allow the bots that cite pages in answers (search and user bots), even if you block training bots." : !robots?.ok ? "Add a robots.txt that names your sitemap." : "",
+    });
+    // sitemap
+    const smPath = robots?.ok ? /^\s*sitemap:\s*(\S+)/im.exec(robots.body)?.[1] : undefined;
+    const sm = await get(smPath ?? origin + "/sitemap.xml", "application/xml, text/xml;q=0.9, */*;q=0.1");
+    const parsed = sm?.ok ? (0, sitemap_1.parseSitemap)(sm.body) : { urls: [], sitemaps: [] };
+    const smCount = parsed.urls.length + parsed.sitemaps.length;
+    add({
+        id: "sitemap",
+        label: "Has a sitemap",
+        status: smCount ? "pass" : "fail",
+        points: 10,
+        detail: smCount ? `${parsed.urls.length} pages${parsed.sitemaps.length ? `, ${parsed.sitemaps.length} child sitemaps` : ""}.` : "No sitemap found.",
+        fix: smCount ? "" : "Publish /sitemap.xml so agents (and the llms.txt builder) can find every page.",
+    });
+    // Structured data and canonical, from the HTML.
+    const ldBlocks = (page.body.match(/<script[^>]+type=["']application\/ld\+json["']/gi) ?? []).length;
+    add({
+        id: "json-ld",
+        label: "Has structured data (JSON-LD)",
+        status: ldBlocks ? "pass" : "warn",
+        points: 10,
+        detail: ldBlocks ? `${ldBlocks} JSON-LD blocks.` : "No JSON-LD on the page.",
+        fix: ldBlocks ? "" : "Add schema.org JSON-LD (Organization, Product, Article, FAQPage…): agents read it for exact facts.",
+    });
+    if (md) {
+        const vary = /\baccept\b/i.test(md.vary);
+        add({
+            id: "vary",
+            label: "Markdown sent with Vary: Accept",
+            status: vary ? "pass" : "warn",
+            points: 5,
+            detail: vary ? "Caches keep HTML and Markdown apart." : "No Vary: Accept on the Markdown.",
+            fix: vary ? "" : "Send Vary: Accept so a cache never gives a browser the Markdown.",
+        });
+    }
+    else {
+        add({ id: "vary", label: "Markdown sent with Vary: Accept", status: "fail", points: 5, detail: "No Markdown served.", fix: "Comes with serving Markdown." });
+    }
+    const canonical = /<link[^>]+rel=["']canonical["']/i.test(page.body) || (md ? /rel="?canonical/i.test(md.link) : false);
+    add({
+        id: "canonical",
+        label: "Names a canonical URL",
+        status: canonical ? "pass" : "warn",
+        points: 5,
+        detail: canonical ? "Agents can cite the right address." : "No canonical link.",
+        fix: canonical ? "" : "Add <link rel=\"canonical\"> so answers cite the right URL.",
+    });
+    if (opts.convert) {
+        try {
+            const c = opts.convert(page.body, { url });
+            if (c?.markdown)
+                report.tokens.converted = (0, enrich_1.estimateTokens)(c.markdown);
+        }
+        catch {
+            // The estimate is a bonus; never fail the check over it.
+        }
+    }
+    return finish(report);
+}
+function finish(r) {
+    const total = r.checks.reduce((s, c) => s + c.points, 0);
+    const earned = r.checks.reduce((s, c) => s + (c.status === "pass" ? c.points : c.status === "warn" ? c.points / 2 : 0), 0);
+    r.score = total ? Math.round((earned / total) * 100) : 0;
+    r.grade = r.score >= 90 ? "A" : r.score >= 75 ? "B" : r.score >= 55 ? "C" : r.score >= 35 ? "D" : "F";
+    return r;
+}
+/**
+ * Bots from `tokens` that robots.txt shuts out of the whole site
+ * ("Disallow: /" in the group that applies to them, with no "Allow: /").
+ * A bot with its own group follows only that group; otherwise "*".
+ */
+function blockedBots(robots, tokens) {
+    const groups = [];
+    let cur = null;
+    for (const raw of robots.split(/\r?\n/)) {
+        const line = raw.replace(/#.*$/, "").trim();
+        const m = /^([A-Za-z-]+)\s*:\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const field = m[1].toLowerCase();
+        const value = m[2].trim();
+        if (field === "user-agent") {
+            if (!cur || cur.rules.length)
+                groups.push((cur = { agents: [], rules: [] }));
+            cur.agents.push(value.toLowerCase());
+        }
+        else if ((field === "disallow" || field === "allow") && cur) {
+            cur.rules.push(`${field}:${value}`);
+        }
+    }
+    const blocks = (rules) => rules.includes("disallow:/") && !rules.includes("allow:/");
+    const star = groups.filter((g) => g.agents.includes("*")).flatMap((g) => g.rules);
+    return tokens.filter((t) => {
+        const own = groups.filter((g) => g.agents.includes(t.toLowerCase())).flatMap((g) => g.rules);
+        return blocks(own.length ? own : star);
+    });
+}
+/** The report as terminal lines (`agent-ready check`). */
+function formatAudit(r) {
+    const mark = { pass: "PASS", warn: "WARN", fail: "FAIL" };
+    const lines = [`agent-ready check  ${r.url}`, ""];
+    if (r.error)
+        return [...lines, `  ${r.error}`].join("\n");
+    lines.push(`  Score ${r.score}/100  (grade ${r.grade})`, "");
+    for (const c of r.checks.filter((c) => c.id !== "page")) {
+        lines.push(`  ${mark[c.status]}  ${c.label}  ${c.detail}`);
+        if (c.fix)
+            lines.push(`        -> ${c.fix}`);
+    }
+    const t = r.tokens;
+    lines.push("", `  An agent reading this page today: ${fmt(t.served ?? t.html ?? 0)} tokens${t.served ? " (Markdown)" : " (HTML)"}.`);
+    if (!t.served && t.converted && t.html) {
+        lines.push(`  With agent-ready: about ${fmt(t.converted)} tokens (${Math.round((1 - t.converted / t.html) * 100)}% less), before custom files.`);
+    }
+    else if (t.served && t.html) {
+        lines.push(`  Markdown is ${Math.round((1 - t.served / t.html) * 100)}% smaller than the HTML (${fmt(t.html)} tokens).`);
+    }
+    return lines.join("\n");
+}
+async function timed(f, url, accept, ms) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), ms);
+    try {
+        const res = await f(url, { headers: { accept, "user-agent": UA }, redirect: "follow", signal: ctl.signal });
+        const body = await res.text();
+        return {
+            ok: res.ok,
+            status: res.status,
+            type: res.headers.get("content-type") ?? "",
+            vary: res.headers.get("vary") ?? "",
+            link: res.headers.get("link") ?? "",
+            body: body.slice(0, 5000000),
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function isMarkdown(type) {
+    return /text\/(markdown|x-markdown)/i.test(type);
+}
+function normalizeUrl(raw) {
+    const withScheme = /^https?:\/\//i.test(raw.trim()) ? raw.trim() : `https://${raw.trim()}`;
+    const u = new URL(withScheme);
+    u.hash = "";
+    return u.href;
+}
+function fmt(x) {
+    return x.toLocaleString("en-US");
+}

package/dist/proof/bots.d.ts

@@ -0,0 +1,24 @@
+export type BotKind = 
+/** Fetches pages to answer one person's question right now. */
+"ai_assistant"
+/** Builds an AI search index (answers cite the page). */
+ | "ai_search"
+/** Collects training data. */
+ | "ai_training"
+/** Classic search engine. */
+ | "search"
+/** A script or HTTP library (curl, python-requests…). */
+ | "tool"
+/** Anything else, including browsers. */
+ | "unknown";
+export interface Bot {
+    id: string;
+    label: string;
+    operator: string;
+    kind: BotKind;
+}
+export declare function classifyAgent(userAgent: string | null | undefined): Bot;
+/** True for the bots that read pages FOR an AI answer (assistants and AI search). */
+export declare function isAnswerBot(bot: Bot): boolean;
+/** The robots.txt tokens the checker looks at: the bots that cite pages in answers. */
+export declare const ANSWER_BOT_TOKENS: string[];

package/dist/proof/bots.js

@@ -0,0 +1,60 @@
+"use strict";
+// Proof: who is reading? A user agent -> a known AI bot (or not).
+// Used only to REPORT on visits, never to choose what to serve (that would be
+// cloaking; serving is decided by the request: Accept, .md, ?format=md).
+//
+// Matching is by case-insensitive substring, in list order: specific names
+// come before broader ones ("Claude-SearchBot" before "ClaudeBot",
+// "Perplexity-User" before "PerplexityBot", "Applebot-Extended" before "Applebot").
+// EDGE-SAFE (pure).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANSWER_BOT_TOKENS = void 0;
+exports.classifyAgent = classifyAgent;
+exports.isAnswerBot = isAnswerBot;
+const BOTS = [
+    { id: "chatgpt-user", label: "ChatGPT-User", operator: "OpenAI", kind: "ai_assistant", needle: "chatgpt-user" },
+    { id: "oai-searchbot", label: "OAI-SearchBot", operator: "OpenAI", kind: "ai_search", needle: "oai-searchbot" },
+    { id: "gptbot", label: "GPTBot", operator: "OpenAI", kind: "ai_training", needle: "gptbot" },
+    { id: "claude-user", label: "Claude-User", operator: "Anthropic", kind: "ai_assistant", needle: "claude-user" },
+    { id: "claude-searchbot", label: "Claude-SearchBot", operator: "Anthropic", kind: "ai_search", needle: "claude-searchbot" },
+    { id: "claudebot", label: "ClaudeBot", operator: "Anthropic", kind: "ai_training", needle: "claudebot" },
+    { id: "anthropic-ai", label: "anthropic-ai", operator: "Anthropic", kind: "ai_training", needle: "anthropic-ai" },
+    { id: "perplexity-user", label: "Perplexity-User", operator: "Perplexity", kind: "ai_assistant", needle: "perplexity-user" },
+    { id: "perplexitybot", label: "PerplexityBot", operator: "Perplexity", kind: "ai_search", needle: "perplexitybot" },
+    { id: "mistralai-user", label: "MistralAI-User", operator: "Mistral", kind: "ai_assistant", needle: "mistralai-user" },
+    { id: "duckassistbot", label: "DuckAssistBot", operator: "DuckDuckGo", kind: "ai_assistant", needle: "duckassistbot" },
+    { id: "meta-externalfetcher", label: "Meta-ExternalFetcher", operator: "Meta", kind: "ai_assistant", needle: "meta-externalfetcher" },
+    { id: "meta-externalagent", label: "meta-externalagent", operator: "Meta", kind: "ai_training", needle: "meta-externalagent" },
+    { id: "youbot", label: "YouBot", operator: "You.com", kind: "ai_search", needle: "youbot" },
+    { id: "cohere-ai", label: "cohere-ai", operator: "Cohere", kind: "ai_training", needle: "cohere-ai" },
+    { id: "bytespider", label: "Bytespider", operator: "ByteDance", kind: "ai_training", needle: "bytespider" },
+    { id: "ccbot", label: "CCBot", operator: "Common Crawl", kind: "ai_training", needle: "ccbot" },
+    { id: "amazonbot", label: "Amazonbot", operator: "Amazon", kind: "search", needle: "amazonbot" },
+    { id: "applebot-extended", label: "Applebot-Extended", operator: "Apple", kind: "ai_training", needle: "applebot-extended" },
+    { id: "applebot", label: "Applebot", operator: "Apple", kind: "search", needle: "applebot" },
+    { id: "googlebot", label: "Googlebot", operator: "Google", kind: "search", needle: "googlebot" },
+    { id: "bingbot", label: "Bingbot", operator: "Microsoft", kind: "search", needle: "bingbot" },
+    { id: "curl", label: "curl", operator: "script", kind: "tool", needle: "curl/" },
+    { id: "python", label: "Python", operator: "script", kind: "tool", needle: "python-" },
+    { id: "node", label: "Node fetch", operator: "script", kind: "tool", needle: "node-fetch" },
+    { id: "undici", label: "Node fetch", operator: "script", kind: "tool", needle: "undici" },
+];
+const UNKNOWN = { id: "unknown", label: "Other", operator: "-", kind: "unknown" };
+function classifyAgent(userAgent) {
+    const ua = (userAgent ?? "").toLowerCase();
+    if (!ua)
+        return UNKNOWN;
+    for (const b of BOTS) {
+        if (ua.includes(b.needle)) {
+            const { needle: _needle, ...bot } = b;
+            return bot;
+        }
+    }
+    return UNKNOWN;
+}
+/** True for the bots that read pages FOR an AI answer (assistants and AI search). */
+function isAnswerBot(bot) {
+    return bot.kind === "ai_assistant" || bot.kind === "ai_search";
+}
+/** The robots.txt tokens the checker looks at: the bots that cite pages in answers. */
+exports.ANSWER_BOT_TOKENS = ["OAI-SearchBot", "ChatGPT-User", "Claude-SearchBot", "Claude-User", "PerplexityBot", "Perplexity-User"];

package/dist/proof/dashboard.d.ts

@@ -0,0 +1,8 @@
+import type { HitSummary } from "./stats";
+export interface DashboardOptions {
+    /** Shown in the heading, e.g. "relvehq.com". */
+    site: string;
+    /** Days the summary covers, shown in the heading. */
+    days?: number;
+}
+export declare function renderDashboard(s: HitSummary, opts: DashboardOptions): string;

package/dist/proof/dashboard.js

@@ -0,0 +1,77 @@
+"use strict";
+// Proof: the dashboard page. A summary -> one self-contained HTML page
+// (inline CSS, no scripts, light and dark). Every value from a request
+// (paths, user agents) is escaped. EDGE-SAFE (pure).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDashboard = renderDashboard;
+const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const n = (x) => x.toLocaleString("en-US");
+function renderDashboard(s, opts) {
+    const tiles = [
+        ["Agent requests", n(s.total)],
+        ["Served as Markdown", n(s.served)],
+        ["From AI assistants & AI search", n(s.answerBotHits)],
+        ["Tokens served", n(s.tokensServed)],
+        ["Median response", s.medianMs === null ? "–" : `${s.medianMs} ms`],
+    ];
+    const range = s.from && s.to ? `${s.from.slice(0, 10)} to ${s.to.slice(0, 10)}` : "no visits yet";
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>Agent visits · ${esc(opts.site)}</title>
+<style>
+:root{--bg:#f7f7f5;--card:#fff;--ink:#1c1c1a;--muted:#6b6b66;--line:#e4e3de;--accent:#d97706;color-scheme:light}
+@media (prefers-color-scheme:dark){:root{--bg:#141413;--card:#1d1d1b;--ink:#ecebe6;--muted:#a3a29b;--line:#2f2e2b;--accent:#f59e0b;color-scheme:dark}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif;padding:24px 16px}
+main{max-width:1040px;margin:0 auto;display:grid;gap:20px}
+h1{font-size:24px;margin:0}h2{font-size:13px;letter-spacing:.08em;text-transform:uppercase;color:var(--muted);margin:0 0 10px}
+.sub{color:var(--muted);margin:4px 0 0}
+.tiles{display:grid;gap:10px;grid-template-columns:repeat(auto-fit,minmax(170px,1fr))}
+.tile,.card{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:14px 16px}
+.tile b{display:block;font-size:24px;font-variant-numeric:tabular-nums}.tile span{color:var(--muted);font-size:13px}
+.grid{display:grid;gap:20px;grid-template-columns:repeat(auto-fit,minmax(320px,1fr))}
+table{width:100%;border-collapse:collapse;font-size:14px}td,th{padding:6px 4px;border-top:1px solid var(--line);text-align:left;vertical-align:top}
+th{font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);border-top:0}
+td.num{text-align:right;font-variant-numeric:tabular-nums;white-space:nowrap}td.path{word-break:break-all;font-family:ui-monospace,Menlo,monospace;font-size:13px}
+.bar{height:6px;background:var(--line);border-radius:3px;margin-top:4px}.bar i{display:block;height:6px;background:var(--accent);border-radius:3px}
+.days{display:flex;align-items:flex-end;gap:2px;height:90px;overflow-x:auto}.days i{flex:1 0 6px;background:var(--accent);border-radius:2px 2px 0 0;min-height:1px}
+.muted{color:var(--muted)}
+</style>
+</head>
+<body>
+<main>
+<header>
+<h1>Agent visits · ${esc(opts.site)}</h1>
+<p class="sub">${esc(range)}${opts.days ? ` · last ${esc(opts.days)} days` : ""} · Markdown served by @relvehq/agent-ready</p>
+</header>
+<section class="tiles" aria-label="Totals">${tiles.map(([label, value]) => `<div class="tile"><b>${esc(value)}</b><span>${esc(label)}</span></div>`).join("")}</section>
+${s.daily.length ? `<section class="card" aria-label="Requests per day"><h2>Requests per day</h2><div class="days">${daysBars(s.daily)}</div><p class="sub">${esc(s.daily[0].day)} to ${esc(s.daily[s.daily.length - 1].day)}</p></section>` : ""}
+<div class="grid">
+${card("Who is reading", s.byBot, (r) => `${esc(r.label)} <span class="muted">· ${esc(r.operator ?? "")}</span>`)}
+${card("Kind of reader", s.byKind)}
+${card("Top pages", s.byPath, (r) => esc(r.label), true)}
+${card("How agents asked", s.byVia)}
+${card("Where the Markdown came from", s.bySource)}
+${card("Status codes", s.byStatus)}
+</div>
+<p class="sub">Bots are recognised from their user agent for reporting only; what is served never depends on it.</p>
+</main>
+</body>
+</html>`;
+}
+function card(title, rows, label = (r) => esc(r.label), path = false) {
+    const max = Math.max(1, ...rows.map((r) => r.hits));
+    const body = rows.length
+        ? rows
+            .map((r) => `<tr><td${path ? ' class="path"' : ""}>${label(r)}<div class="bar"><i style="width:${Math.max(2, Math.round((r.hits / max) * 100))}%"></i></div></td><td class="num">${n(r.hits)}</td><td class="num muted">${r.tokens ? n(r.tokens) : "–"}</td></tr>`)
+            .join("")
+        : `<tr><td colspan="3" class="muted">Nothing yet</td></tr>`;
+    return `<section class="card"><h2>${esc(title)}</h2><table><thead><tr><th scope="col"></th><th scope="col" class="num">Hits</th><th scope="col" class="num">Tokens</th></tr></thead><tbody>${body}</tbody></table></section>`;
+}
+function daysBars(days) {
+    const max = Math.max(1, ...days.map((d) => d.hits));
+    return days.map((d) => `<i title="${esc(d.day)}: ${n(d.hits)}" style="height:${Math.round((d.hits / max) * 100)}%"></i>`).join("");
+}

package/dist/proof/hits.d.ts

@@ -0,0 +1,18 @@
+import type { Awaitable, HitEvent } from "../core/config";
+export interface HitQuery {
+    /** ISO time; only hits at or after it. */
+    since?: string;
+    /** Newest N. */
+    limit?: number;
+}
+export interface HitStore {
+    add(event: HitEvent): Awaitable<void>;
+    list(query?: HitQuery): Awaitable<HitEvent[]>;
+}
+/** In memory, newest `max` kept. */
+export declare function memoryHitStore(max?: number): HitStore & {
+    size(): number;
+};
+/** Several onHit handlers as one. Nulls are skipped; one failing never stops the others. */
+export declare function teeHits(...handlers: Array<((e: HitEvent) => Awaitable<void>) | null | undefined>): (e: HitEvent) => Promise<void>;
+export declare function filterHits(events: HitEvent[], q?: HitQuery): HitEvent[];

package/dist/proof/hits.js

@@ -0,0 +1,51 @@
+"use strict";
+// Proof: keep the visits. A HitStore records every HitEvent and lists them
+// back for the dashboard and `agent-ready stats`.
+//
+//   const hits = memoryHitStore();                 // dev, tests
+//   const hits = jsonlHitStore("hits.jsonl");      // a long-running Node server (proof/jsonl)
+//   onHit: hits.add                                // or teeHits(hits.add, reporterFromEnv(env))
+//
+// On serverless hosts (Amplify, Vercel) memory and local files don't last
+// between requests: send hits to the dashboard endpoint (core/report) or to a
+// database HitStore of your own. EDGE-SAFE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryHitStore = memoryHitStore;
+exports.teeHits = teeHits;
+exports.filterHits = filterHits;
+/** In memory, newest `max` kept. */
+function memoryHitStore(max = 10000) {
+    const events = [];
+    return {
+        add(e) {
+            events.push(e);
+            if (events.length > max)
+                events.splice(0, events.length - max);
+        },
+        list(q = {}) {
+            return filterHits(events, q);
+        },
+        size: () => events.length,
+    };
+}
+/** Several onHit handlers as one. Nulls are skipped; one failing never stops the others. */
+function teeHits(...handlers) {
+    const live = handlers.filter((h) => typeof h === "function");
+    return async (e) => {
+        await Promise.all(live.map(async (h) => {
+            try {
+                await h(e);
+            }
+            catch {
+                // A logging failure never touches the response or the other loggers.
+            }
+        }));
+    };
+}
+function filterHits(events, q = {}) {
+    let out = q.since ? events.filter((e) => e.ts >= q.since) : events.slice();
+    out.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+    if (q.limit && out.length > q.limit)
+        out = out.slice(out.length - q.limit);
+    return out;
+}

package/dist/proof/jsonl.d.ts

@@ -0,0 +1,5 @@
+import type { HitEvent } from "../core/config";
+import { type HitStore } from "./hits";
+export declare function jsonlHitStore(file: string): HitStore;
+/** Lines that aren't a hit (blank, broken, foreign) are skipped. */
+export declare function parseJsonl(text: string): HitEvent[];

package/dist/proof/jsonl.js

@@ -0,0 +1,80 @@
+"use strict";
+// A HitStore in a JSON Lines file: one HitEvent per line, appended.
+// For a long-running Node server or local testing; `agent-ready stats --log`
+// reads the same file. NODE ONLY (node:fs, loaded on first use).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonlHitStore = jsonlHitStore;
+exports.parseJsonl = parseJsonl;
+const hits_1 = require("./hits");
+function jsonlHitStore(file) {
+    const fs = () => Promise.resolve().then(() => __importStar(require("node:fs/promises")));
+    return {
+        async add(e) {
+            const f = await fs();
+            const dir = file.replace(/[\\/][^\\/]*$/, "");
+            if (dir && dir !== file)
+                await f.mkdir(dir, { recursive: true });
+            await f.appendFile(file, JSON.stringify(e) + "\n", "utf8");
+        },
+        async list(q) {
+            let text;
+            try {
+                text = await (await fs()).readFile(file, "utf8");
+            }
+            catch {
+                return [];
+            }
+            return (0, hits_1.filterHits)(parseJsonl(text), q);
+        },
+    };
+}
+/** Lines that aren't a hit (blank, broken, foreign) are skipped. */
+function parseJsonl(text) {
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (e && typeof e.ts === "string" && typeof e.path === "string")
+                out.push(e);
+        }
+        catch {
+            // skip
+        }
+    }
+    return out;
+}

package/dist/proof/stats.d.ts

@@ -0,0 +1,39 @@
+import type { HitEvent } from "../core/config";
+import { type BotKind } from "./bots";
+export interface Count {
+    key: string;
+    label: string;
+    hits: number;
+    tokens: number;
+}
+export interface HitSummary {
+    from: string | null;
+    to: string | null;
+    total: number;
+    /** 2xx and 304 responses. */
+    served: number;
+    /** Hits from AI assistants and AI search (the ones that cite pages). */
+    answerBotHits: number;
+    tokensServed: number;
+    medianMs: number | null;
+    byBot: (Count & {
+        operator: string;
+        kind: BotKind;
+    })[];
+    byKind: Count[];
+    byPath: Count[];
+    byVia: Count[];
+    bySource: Count[];
+    byStatus: Count[];
+    /** One row per day (UTC), oldest first, gaps filled with 0. */
+    daily: {
+        day: string;
+        hits: number;
+        tokens: number;
+    }[];
+}
+export declare function summarize(events: HitEvent[], opts?: {
+    topPaths?: number;
+}): HitSummary;
+/** The summary as terminal lines (`agent-ready stats`). */
+export declare function formatSummary(s: HitSummary): string;