@relvehq/agent-ready 0.0.0-stage → 0.2.1

package/dist/next/index.d.ts

@@ -0,0 +1,42 @@
+import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";
+import { type AgentReadyConfig, type ResolvedAgentReadyConfig } from "../core/config";
+import { type Detection } from "../core/detect";
+export interface AgentReadyMatcher {
+    config: ResolvedAgentReadyConfig;
+    /** A rewrite to the internal Markdown route, or null to carry on as normal. */
+    match(req: NextRequest): NextResponse | null;
+    /** The decision without the response, for logging or tests. */
+    detect(req: NextRequest): Detection | null;
+    /** True for the package's own origin fetch (the internal header is present). */
+    isInternal(req: Request): boolean;
+}
+export declare function agentReady(config: AgentReadyConfig | ResolvedAgentReadyConfig): AgentReadyMatcher;
+/** Any Next.js middleware: may return a response, nothing, or a promise of either. */
+export type Middleware = (req: NextRequest, event: NextFetchEvent) => Response | NextResponse | null | undefined | void | Promise<Response | NextResponse | null | undefined | void>;
+/**
+ * The one-line middleware (changes/agent-ready-engine, "easy setup").
+ *
+ *   // middleware.ts, no middleware of your own
+ *   export default withAgentReady(agentReadyConfig);
+ *
+ *   // middleware.ts, wrapping the one you have
+ *   export default withAgentReady(agentReadyConfig, myMiddleware);
+ *
+ * A Markdown request is rewritten to the internal route; anything else goes
+ * to your middleware unchanged (or straight on, when there is none). Your
+ * middleware never sees Markdown requests, and the package's own origin fetch
+ * still reaches it as a normal request.
+ */
+export declare function withAgentReady(config: AgentReadyConfig | ResolvedAgentReadyConfig, next?: Middleware): Middleware;
+/**
+ * The matcher entries a Markdown-serving middleware needs, for reference and
+ * for the init tool. Next.js reads `export const config = { matcher }`
+ * statically, so copy them into your file as literals (importing this array
+ * does not work there):
+ *   "/((?!_next/|.*\\..*).*)"   pages (no dot in the path)
+ *   "/((?!_next/).+\\.md)"      .md URLs
+ *   "/llms.txt"                 the generated llms.txt
+ */
+export declare const AGENT_READY_MATCHER: readonly string[];
+/** "/tool/x" -> "/__md/tool/x", "/" -> "/__md". */
+export declare function internalPath(cfg: ResolvedAgentReadyConfig, path: string): string;

package/dist/next/index.js

@@ -0,0 +1,100 @@
+"use strict";
+// Next.js middleware adapter for @relvehq/agent-ready.
+//
+//   const md = agentReady(config);
+//   export function middleware(req: NextRequest) {
+//     const hit = md.match(req);
+//     if (hit) return hit;
+//     ...
+//   }
+//
+// `match()` returns a NextResponse.rewrite to the internal route
+// `/__md/<path>` (query preserved) when the request wants Markdown, or null.
+// It returns null, and does no other work, when the package is disabled.
+//
+// The route handler lives in "@relvehq/agent-ready/next/route" (markdownRoute),
+// NOT here: it pulls in linkedom/turndown, which must never be bundled into
+// the Edge middleware.
+//
+// EDGE-SAFE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_READY_MATCHER = void 0;
+exports.agentReady = agentReady;
+exports.withAgentReady = withAgentReady;
+exports.internalPath = internalPath;
+const server_1 = require("next/server");
+const config_1 = require("../core/config");
+const detect_1 = require("../core/detect");
+function agentReady(config) {
+    const cfg = (0, config_1.defineAgentReady)(config);
+    const isInternal = (req) => req.headers.has(cfg.internalHeader);
+    const detect = (req) => {
+        if (req.method !== "GET" && req.method !== "HEAD")
+            return null;
+        if (isInternal(req))
+            return null;
+        const pathname = req.nextUrl.pathname;
+        if (pathname === cfg.internalPrefix || pathname.startsWith(cfg.internalPrefix + "/"))
+            return null;
+        if (!(0, config_1.isEnabled)(cfg, req))
+            return null;
+        const d = (0, detect_1.wantsMarkdown)(req, { llmsPath: cfg.llms ? cfg.llms.path : null });
+        if (!d.markdown)
+            return null;
+        if (!d.llms && (0, config_1.isExcluded)(cfg, d.path))
+            return null;
+        return d;
+    };
+    return {
+        config: cfg,
+        detect,
+        isInternal,
+        match(req) {
+            const d = detect(req);
+            if (!d)
+                return null;
+            const target = new URL(internalPath(cfg, d.path), req.url);
+            target.search = d.search;
+            const headers = new Headers(req.headers);
+            headers.set(config_1.VIA_HEADER, d.via ?? "direct");
+            return server_1.NextResponse.rewrite(target, { request: { headers } });
+        },
+    };
+}
+/**
+ * The one-line middleware (changes/agent-ready-engine, "easy setup").
+ *
+ *   // middleware.ts, no middleware of your own
+ *   export default withAgentReady(agentReadyConfig);
+ *
+ *   // middleware.ts, wrapping the one you have
+ *   export default withAgentReady(agentReadyConfig, myMiddleware);
+ *
+ * A Markdown request is rewritten to the internal route; anything else goes
+ * to your middleware unchanged (or straight on, when there is none). Your
+ * middleware never sees Markdown requests, and the package's own origin fetch
+ * still reaches it as a normal request.
+ */
+function withAgentReady(config, next) {
+    const md = agentReady(config);
+    return (req, event) => {
+        const hit = md.match(req);
+        if (hit)
+            return hit;
+        return next ? next(req, event) : server_1.NextResponse.next();
+    };
+}
+/**
+ * The matcher entries a Markdown-serving middleware needs, for reference and
+ * for the init tool. Next.js reads `export const config = { matcher }`
+ * statically, so copy them into your file as literals (importing this array
+ * does not work there):
+ *   "/((?!_next/|.*\\..*).*)"   pages (no dot in the path)
+ *   "/((?!_next/).+\\.md)"      .md URLs
+ *   "/llms.txt"                 the generated llms.txt
+ */
+exports.AGENT_READY_MATCHER = ["/((?!_next/|.*\\..*).*)", "/((?!_next/).+\\.md)", "/llms.txt"];
+/** "/tool/x" -> "/__md/tool/x", "/" -> "/__md". */
+function internalPath(cfg, path) {
+    return path === "/" ? cfg.internalPrefix : `${cfg.internalPrefix}${path}`;
+}

package/dist/next/route.d.ts

@@ -0,0 +1,26 @@
+import { type AgentReadyConfig, type ResolvedAgentReadyConfig } from "../core/config";
+import { type ResolveDeps } from "../core/resolve";
+type RouteContext = {
+    params?: {
+        path?: string[];
+    };
+};
+export declare function markdownRoute(config: AgentReadyConfig | ResolvedAgentReadyConfig, deps?: ResolveDeps): (req: Request, ctx?: RouteContext) => Promise<Response>;
+/**
+ * The route file in one line (changes/agent-ready-engine, "easy setup"):
+ *
+ *   // app/%5F%5Fmd/[[...path]]/route.ts
+ *   export const { GET, HEAD } = createMarkdownRoute(config);
+ *   export const runtime = "nodejs";        // literals: Next.js reads these
+ *   export const dynamic = "force-dynamic"; // statically, not from a spread
+ *
+ * `runtime` and `dynamic` are returned too, for frameworks that read them at
+ * run time; the init tool writes the two literal lines for Next.js.
+ */
+export declare function createMarkdownRoute(config: AgentReadyConfig | ResolvedAgentReadyConfig, deps?: ResolveDeps): {
+    GET: (req: Request, ctx?: RouteContext) => Promise<Response>;
+    HEAD: (req: Request, ctx?: RouteContext) => Promise<Response>;
+    runtime: "nodejs";
+    dynamic: "force-dynamic";
+};
+export {};

package/dist/next/route.js

@@ -0,0 +1,167 @@
+"use strict";
+// Next.js route handler for @relvehq/agent-ready.
+//
+//   // app/%5F%5Fmd/[[...path]]/route.ts   (serves the URL /__md/...)
+//   import { markdownRoute } from "@relvehq/agent-ready/next/route";
+//   export const GET = markdownRoute(config);
+//   export const HEAD = GET;
+//   export const runtime = "nodejs";
+//   export const dynamic = "force-dynamic";
+//
+// Runs resolve -> enrich -> respond, and serves llms.txt. Disabled -> 404.
+// When no Markdown can be produced:
+//   - Accept-negotiated requests get the page's HTML (the origin response,
+//     passed through), so an agent is never worse off than a browser;
+//   - `.md` / `?format=md` requests get a plain-text 404 (or the origin's 4xx).
+//
+// NODE ONLY (the convert step uses linkedom/turndown).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.markdownRoute = markdownRoute;
+exports.createMarkdownRoute = createMarkdownRoute;
+const config_1 = require("../core/config");
+const detect_1 = require("../core/detect");
+const enrich_1 = require("../core/enrich");
+const llms_1 = require("../core/llms");
+const respond_1 = require("../core/respond");
+const resolve_1 = require("../core/resolve");
+const VIAS = new Set(["accept", "suffix", "query", "llms", "direct"]);
+function markdownRoute(config, deps = {}) {
+    const cfg = (0, config_1.defineAgentReady)(config);
+    return async function GET(req, ctx) {
+        const started = Date.now();
+        if (!(0, config_1.isEnabled)(cfg, req))
+            return plain(404, "Not found");
+        const url = new URL(req.url);
+        const path = pagePath(cfg, url.pathname, ctx);
+        const viaHeader = (req.headers.get(config_1.VIA_HEADER) ?? "direct");
+        const via = VIAS.has(viaHeader) ? viaHeader : "direct";
+        const hit = (status, source, tokens, bytes) => (0, config_1.emitHit)(cfg, {
+            ts: new Date().toISOString(),
+            host: req.headers.get("x-forwarded-host") ?? req.headers.get("host"),
+            path: path ?? url.pathname,
+            via,
+            source,
+            status,
+            tokens,
+            bytes,
+            userAgent: req.headers.get("user-agent")?.slice(0, 512) ?? null,
+            accept: req.headers.get("accept")?.slice(0, 1024) ?? null,
+            durationMs: Date.now() - started,
+        });
+        if (!path) {
+            hit(404, null, null, null);
+            return plain(404, "Not found");
+        }
+        // llms.txt
+        if (cfg.llms && path === cfg.llms.path) {
+            const entries = await Promise.resolve(cfg.llms.entries({ request: req })).catch(() => []);
+            const body = (0, llms_1.buildLlmsTxt)({
+                site: cfg.site,
+                title: cfg.llms.title,
+                summary: cfg.llms.summary,
+                details: cfg.llms.details,
+                entries,
+            });
+            const res = await (0, respond_1.markdownResponse)(body, {
+                request: req,
+                canonical: cfg.site + cfg.llms.path,
+                tokens: Math.ceil(body.length / 4),
+                cacheControl: cfg.cacheControl,
+                contentType: "text/plain; charset=utf-8",
+                headers: { "x-agent-ready-source": "llms" },
+            });
+            // llms.txt is meant to be found and read; it is not a duplicate of a page.
+            res.headers.delete("x-robots-tag");
+            res.headers.delete("link");
+            hit(res.status, "llms", Math.ceil(body.length / 4), (0, respond_1.byteLength)(body));
+            return res;
+        }
+        if ((0, config_1.isExcluded)(cfg, path)) {
+            hit(404, null, null, null);
+            return plain(404, "Not found");
+        }
+        // Keep the query (minus `format`) so query-driven pages convert as asked.
+        const params = new URLSearchParams(url.searchParams);
+        params.delete("format");
+        const qs = params.toString();
+        const search = qs ? `?${qs}` : "";
+        const resolved = await (0, resolve_1.resolveMarkdown)(cfg, { path, search, request: req }, deps);
+        const canonical = cfg.site + (path === "/" ? "" : path);
+        const cacheControl = via === "accept" ? cfg.negotiatedCacheControl : cfg.cacheControl;
+        if (resolved.source === null) {
+            if (via === "accept" && resolved.html) {
+                // Fall back to the HTML the browser would have got.
+                const { status, contentType, body } = resolved.html;
+                hit(status, null, null, (0, respond_1.byteLength)(body));
+                return new Response(req.method === "HEAD" ? null : body, {
+                    status,
+                    headers: {
+                        "content-type": contentType,
+                        vary: "Accept",
+                        "cache-control": cfg.negotiatedCacheControl,
+                        "x-agent-ready-source": "html-fallback",
+                    },
+                });
+            }
+            const status = resolved.originStatus && resolved.originStatus >= 400 && resolved.originStatus < 500
+                ? resolved.originStatus
+                : 404;
+            hit(status, null, null, null);
+            return plain(status, "No Markdown version of this page is available.", { vary: "Accept", link: `<${canonical}>; rel="canonical"` });
+        }
+        const { body, tokens } = (0, enrich_1.enrich)(resolved.doc, {
+            canonical: resolved.doc.canonical || canonical,
+            sourceUrl: resolved.sourceUrl,
+            source: resolved.source,
+        });
+        const res = await (0, respond_1.markdownResponse)(body, {
+            request: req,
+            canonical: resolved.doc.canonical || canonical,
+            tokens,
+            cacheControl,
+            headers: { "x-agent-ready-source": resolved.source },
+        });
+        hit(res.status, resolved.source, tokens, (0, respond_1.byteLength)(body));
+        return res;
+    };
+}
+/**
+ * The route file in one line (changes/agent-ready-engine, "easy setup"):
+ *
+ *   // app/%5F%5Fmd/[[...path]]/route.ts
+ *   export const { GET, HEAD } = createMarkdownRoute(config);
+ *   export const runtime = "nodejs";        // literals: Next.js reads these
+ *   export const dynamic = "force-dynamic"; // statically, not from a spread
+ *
+ * `runtime` and `dynamic` are returned too, for frameworks that read them at
+ * run time; the init tool writes the two literal lines for Next.js.
+ */
+function createMarkdownRoute(config, deps = {}) {
+    const GET = markdownRoute(config, deps);
+    return { GET, HEAD: GET, runtime: "nodejs", dynamic: "force-dynamic" };
+}
+/** The page path behind an internal URL: "/__md/tool/x" -> "/tool/x", "/__md" -> "/". */
+function pagePath(cfg, pathname, ctx) {
+    const prefix = cfg.internalPrefix;
+    let raw;
+    if (pathname === prefix || pathname.startsWith(prefix + "/")) {
+        raw = pathname.slice(prefix.length) || "/";
+    }
+    else if (ctx?.params) {
+        // In a production build (`next start`) the handler sees the ORIGINAL URL
+        // ("/index.md", "/pricing.md"), not the rewrite target. The catch-all
+        // params are the truth; no `path` param means the home page. Found in
+        // the fresh-app install test, 2026-10-21: /index.md answered 404.
+        raw = ctx.params.path?.length ? "/" + ctx.params.path.map(encodeURIComponent).join("/") : "/";
+    }
+    else {
+        raw = (0, detect_1.stripMdSuffix)(pathname) ?? pathname;
+    }
+    return (0, detect_1.normalizePath)(raw);
+}
+function plain(status, text, extra = {}) {
+    return new Response(text, {
+        status,
+        headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", ...extra },
+    });
+}

package/dist/node/index.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type AgentReadyConfig, type ResolvedAgentReadyConfig } from "../core/config";
+import { type ResolveDeps } from "../core/resolve";
+/** Connect's `next`: no argument carries on, an argument is an error. */
+export type NodeNext = (err?: unknown) => void;
+/** A `(req, res, next)` middleware. Express's req/res extend these types. */
+export type NodeMiddleware = (req: IncomingMessage, res: ServerResponse, next?: NodeNext) => void;
+export declare function agentReadyNode(config: AgentReadyConfig | ResolvedAgentReadyConfig, deps?: ResolveDeps): NodeMiddleware;

package/dist/node/index.js

@@ -0,0 +1,191 @@
+"use strict";
+// Node adapter for @relvehq/agent-ready: one Connect-style middleware.
+//
+//   // Express, Connect, Polka (Fastify: via @fastify/middie)
+//   import { createAgentReady } from "@relvehq/agent-ready";
+//   import { agentReadyNode } from "@relvehq/agent-ready/node";
+//   app.use(agentReadyNode(createAgentReady({ site: "https://your-site.com" })));
+//
+//   // plain http
+//   const md = agentReadyNode(config);
+//   http.createServer((req, res) => md(req, res, () => app(req, res)));
+//
+// Mount it before static files and routes. Same detect -> resolve -> enrich
+// -> respond path as the Next.js adapter and route, in one step (no rewrite):
+//   - not a Markdown request, disabled, excluded, not GET/HEAD, or the
+//     package's own origin fetch: next(), nothing written;
+//   - nothing resolves: an Accept request goes on to next() (the app serves
+//     its HTML), a `.md` / `?format=md` request gets a 404;
+//   - resolving throws: next() for Accept (the error never reaches the
+//     client), next(err) for `.md` / `?format=md`.
+//
+// NODE ONLY (the convert step uses linkedom/turndown).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentReadyNode = agentReadyNode;
+const config_1 = require("../core/config");
+const detect_1 = require("../core/detect");
+const enrich_1 = require("../core/enrich");
+const llms_1 = require("../core/llms");
+const respond_1 = require("../core/respond");
+const resolve_1 = require("../core/resolve");
+function agentReadyNode(config, deps = {}) {
+    const cfg = (0, config_1.defineAgentReady)(config);
+    return function agentReadyMiddleware(req, res, next) {
+        // Plain http with no next(): what would have been "carry on" is a 404.
+        const done = next ??
+            ((err) => {
+                if (res.headersSent)
+                    return void res.end();
+                res.statusCode = err ? 500 : 404;
+                res.setHeader("content-type", "text/plain; charset=utf-8");
+                res.end(err ? "Internal Server Error" : "Not found");
+            });
+        handle(cfg, deps, req, res, done).catch((err) => {
+            // Only reached when writing the response failed part-way.
+            if (!res.headersSent)
+                done(err);
+            else
+                res.destroy(err);
+        });
+    };
+}
+async function handle(cfg, deps, req, res, next) {
+    const method = (req.method ?? "GET").toUpperCase();
+    if (method !== "GET" && method !== "HEAD")
+        return next();
+    if (req.headers[cfg.internalHeader] !== undefined)
+        return next();
+    const request = toRequest(cfg, req, method);
+    const pathname = new URL(request.url).pathname;
+    if (pathname === cfg.internalPrefix || pathname.startsWith(cfg.internalPrefix + "/"))
+        return next();
+    if (!(0, config_1.isEnabled)(cfg, request))
+        return next();
+    const d = (0, detect_1.wantsMarkdown)(request, { llmsPath: cfg.llms ? cfg.llms.path : null });
+    if (!d.markdown)
+        return next();
+    if (!d.llms && (0, config_1.isExcluded)(cfg, d.path))
+        return next();
+    const started = Date.now();
+    const via = d.via ?? "direct";
+    const hit = (status, source, tokens, bytes) => (0, config_1.emitHit)(cfg, {
+        ts: new Date().toISOString(),
+        host: request.headers.get("x-forwarded-host") ?? request.headers.get("host"),
+        path: d.path,
+        via,
+        source,
+        status,
+        tokens,
+        bytes,
+        userAgent: request.headers.get("user-agent")?.slice(0, 512) ?? null,
+        accept: request.headers.get("accept")?.slice(0, 1024) ?? null,
+        durationMs: Date.now() - started,
+    });
+    // llms.txt
+    if (d.llms && cfg.llms) {
+        const entries = await Promise.resolve()
+            .then(() => cfg.llms.entries({ request }))
+            .catch(() => []);
+        const body = (0, llms_1.buildLlmsTxt)({
+            site: cfg.site,
+            title: cfg.llms.title,
+            summary: cfg.llms.summary,
+            details: cfg.llms.details,
+            entries,
+        });
+        const r = await (0, respond_1.markdownResponse)(body, {
+            request,
+            canonical: cfg.site + cfg.llms.path,
+            tokens: Math.ceil(body.length / 4),
+            cacheControl: cfg.cacheControl,
+            contentType: "text/plain; charset=utf-8",
+            headers: { "x-agent-ready-source": "llms" },
+        });
+        // llms.txt is meant to be found and read; it is not a duplicate of a page.
+        r.headers.delete("x-robots-tag");
+        r.headers.delete("link");
+        hit(r.status, "llms", Math.ceil(body.length / 4), (0, respond_1.byteLength)(body));
+        return send(res, r);
+    }
+    let resolved;
+    try {
+        resolved = await (0, resolve_1.resolveMarkdown)(cfg, { path: d.path, search: d.search, request }, deps);
+    }
+    catch (err) {
+        // An agent asking by Accept is never worse off than a browser.
+        if (via === "accept")
+            return next();
+        return next(err);
+    }
+    const canonical = cfg.site + (d.path === "/" ? "" : d.path);
+    if (resolved.source === null) {
+        // Accept: the app serves its HTML (no hit: the status is the app's, not ours).
+        if (via === "accept")
+            return next();
+        const status = resolved.originStatus && resolved.originStatus >= 400 && resolved.originStatus < 500
+            ? resolved.originStatus
+            : 404;
+        hit(status, null, null, null);
+        return send(res, plain(status, "No Markdown version of this page is available.", { vary: "Accept", link: `<${canonical}>; rel="canonical"` }), method);
+    }
+    const { body, tokens } = (0, enrich_1.enrich)(resolved.doc, {
+        canonical: resolved.doc.canonical || canonical,
+        sourceUrl: resolved.sourceUrl,
+        source: resolved.source,
+    });
+    const r = await (0, respond_1.markdownResponse)(body, {
+        request,
+        canonical: resolved.doc.canonical || canonical,
+        tokens,
+        cacheControl: via === "accept" ? cfg.negotiatedCacheControl : cfg.cacheControl,
+        headers: { "x-agent-ready-source": resolved.source },
+    });
+    hit(r.status, resolved.source, tokens, (0, respond_1.byteLength)(body));
+    return send(res, r);
+}
+/**
+ * The Node request as a WHATWG Request (no body: only GET and HEAD get here).
+ * The origin is the Host the request came in on, so the convert step fetches
+ * this same server; without a Host header, the configured site.
+ */
+function toRequest(cfg, req, method) {
+    // Express rewrites req.url under a mount path; originalUrl is what was asked.
+    const raw = req.originalUrl ?? req.url ?? "/";
+    const host = req.headers.host;
+    const tls = req.socket?.encrypted === true;
+    const proto = (String(req.headers["x-forwarded-proto"] ?? "").split(",")[0].trim() || (tls ? "https" : "http"));
+    let url;
+    try {
+        url = host ? new URL(raw, `${proto}://${host}`) : new URL(raw, cfg.site);
+    }
+    catch {
+        url = new URL(cfg.site);
+    }
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        try {
+            headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+        }
+        catch {
+            // A header value fetch won't accept: leave it out.
+        }
+    }
+    return new Request(url, { method, headers });
+}
+/** Write a Response to the Node response: status, headers, then the body. */
+async function send(res, r, method) {
+    res.statusCode = r.status;
+    r.headers.forEach((value, name) => res.setHeader(name, value));
+    const body = r.body && method !== "HEAD" ? Buffer.from(await r.arrayBuffer()) : null;
+    if (body)
+        res.setHeader("content-length", String(body.length));
+    res.end(body ?? undefined);
+}
+function plain(status, text, extra = {}) {
+    return new Response(text, {
+        status,
+        headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", ...extra },
+    });
+}

package/dist/proof/audit.d.ts

@@ -0,0 +1,47 @@
+export type CheckStatus = "pass" | "warn" | "fail";
+export interface AuditCheck {
+    id: string;
+    label: string;
+    status: CheckStatus;
+    points: number;
+    detail: string;
+    /** What to do about it (empty on pass). */
+    fix: string;
+}
+export interface AuditReport {
+    url: string;
+    checkedAt: string;
+    ok: boolean;
+    /** Set when the page itself could not be loaded. */
+    error: string | null;
+    score: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    checks: AuditCheck[];
+    tokens: {
+        html: number | null;
+        /** Markdown the site served itself (Accept or .md). */
+        served: number | null;
+        /** What the package's converter would make of the page (when `convert` is given). */
+        converted: number | null;
+    };
+}
+export interface AuditOptions {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    /** HTML -> Markdown, to show what the site could serve. */
+    convert?: (html: string, opts: {
+        url: string;
+    }) => {
+        markdown: string;
+    } | null;
+    now?: () => Date;
+}
+export declare function auditSite(rawUrl: string, opts?: AuditOptions): Promise<AuditReport>;
+/**
+ * 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 "*".
+ */
+export declare function blockedBots(robots: string, tokens: string[]): string[];
+/** The report as terminal lines (`agent-ready check`). */
+export declare function formatAudit(r: AuditReport): string;