@relvehq/agent-ready 0.0.0-stage → 0.3.0

package/dist/core/easy.js

@@ -0,0 +1,117 @@
+"use strict";
+// The easy front door (changes/agent-ready-engine, "easy setup"): a full
+// config from almost nothing.
+//
+//   export default createAgentReady();                       // all defaults
+//   export default createAgentReady({ exclude: ["/members"] });
+//
+// What it works out on its own:
+//   site      NEXT_PUBLIC_SITE_URL, SITE_URL, NEXT_PUBLIC_APP_URL, URL
+//             (Netlify), VERCEL_PROJECT_PRODUCTION_URL, VERCEL_URL, in that order
+//   enabled   AGENT_READY_ENABLED = "1" | "true" (off otherwise)
+//   exclude   the always-excluded list + common private pages (account,
+//             checkout, cart, dashboard, settings, billing...) + yours
+//   llms      /llms.txt built from the site's sitemap.xml, titled from the
+//             site's host (pass `llms: false` to serve none, or your own)
+//   onHit     dashboard reporting when AGENT_READY_KEY + AGENT_READY_ENDPOINT
+//             are set; nothing otherwise. `hits: store` records every visit
+//             in a HitStore as well (proof/hits), for the built-in dashboard
+// Anything passed explicitly wins. The result is a plain resolved config, so
+// it goes everywhere `defineAgentReady()`'s does.
+//
+// EDGE-SAFE. Reads `process.env` only through the injectable `env`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_SITE_WARNING = exports.COMMON_PRIVATE_PATHS = void 0;
+exports.siteFromEnv = siteFromEnv;
+exports.enabledFromEnv = enabledFromEnv;
+exports.createAgentReady = createAgentReady;
+const config_1 = require("./config");
+const report_1 = require("./report");
+const hits_1 = require("../proof/hits");
+const sitemap_1 = require("./sitemap");
+/** Private pages most sites have, never served as Markdown by the easy config. */
+exports.COMMON_PRIVATE_PATHS = [
+    "/account",
+    "/accounts",
+    "/my-account",
+    "/profile",
+    "/settings",
+    "/dashboard",
+    "/billing",
+    "/checkout",
+    "/cart",
+    "/orders",
+    "/admin",
+    "/register",
+    "/reset-password",
+    "/forgot-password",
+    "/verify",
+    "/oauth",
+    "/callback",
+    "/preview",
+    "/draft",
+];
+const SITE_VARS = ["NEXT_PUBLIC_SITE_URL", "SITE_URL", "NEXT_PUBLIC_APP_URL", "URL", "VERCEL_PROJECT_PRODUCTION_URL", "VERCEL_URL"];
+/** The site's public origin from the usual env vars, or null. */
+function siteFromEnv(env) {
+    for (const name of SITE_VARS) {
+        const raw = env[name]?.trim();
+        if (!raw)
+            continue;
+        // Vercel's vars are bare hosts ("acme.vercel.app").
+        const withScheme = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+        try {
+            return new URL(withScheme).origin;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/** AGENT_READY_ENABLED is "1" or "true". */
+function enabledFromEnv(env) {
+    const v = env.AGENT_READY_ENABLED?.trim().toLowerCase();
+    return v === "1" || v === "true";
+}
+function createAgentReady(options = {}, env = readEnv()) {
+    const { excludeCommon = true, llms, hits, ...rest } = options;
+    // No site URL: stay OFF and say so, never throw. A throw here would fail the
+    // venture's whole `next build` over one missing env var (seen in the
+    // fresh-app install test, 2026-10-21).
+    const found = rest.site ?? siteFromEnv(env);
+    if (!found)
+        warnOnce(exports.NO_SITE_WARNING);
+    const site = found ?? "http://localhost:3000";
+    const userExclude = rest.exclude ?? [];
+    const exclude = excludeCommon ? [...exports.COMMON_PRIVATE_PATHS, ...userExclude] : userExclude;
+    const host = new URL(site).hostname.replace(/^www\./, "");
+    const resolvedLlms = llms === false || llms === null
+        ? null
+        : llms ?? {
+            path: "/llms.txt",
+            title: host,
+            details: "Every page below is also available as Markdown: add `.md` to its URL or send `Accept: text/markdown`.",
+            entries: (0, sitemap_1.sitemapEntries)({ exclude }),
+        };
+    return (0, config_1.defineAgentReady)({
+        ...rest,
+        site,
+        enabled: found ? rest.enabled ?? enabledFromEnv(env) : false,
+        exclude,
+        llms: resolvedLlms,
+        onHit: hits ? (0, hits_1.teeHits)((e) => hits.add(e), rest.onHit ?? (0, report_1.reporterFromEnv)(env)) : rest.onHit ?? (0, report_1.reporterFromEnv)(env) ?? undefined,
+    });
+}
+exports.NO_SITE_WARNING = "agent-ready: no site URL, so it stays off. Set NEXT_PUBLIC_SITE_URL (e.g. https://example.com) or pass createAgentReady({ site }).";
+const warned = new Set();
+function warnOnce(message) {
+    if (warned.has(message))
+        return;
+    warned.add(message);
+    console.warn(message);
+}
+function readEnv() {
+    // `process` is absent in some runtimes; Next.js inlines what it can at build.
+    return typeof process !== "undefined" && process.env ? process.env : {};
+}

package/dist/core/enrich.d.ts

@@ -0,0 +1,30 @@
+import type { MarkdownDoc, Source } from "./config";
+export interface EnrichMeta {
+    /** Absolute canonical URL of the HTML page. */
+    canonical: string;
+    /** Absolute URL the Markdown was produced from (the HTML page). */
+    sourceUrl: string;
+    source: Source;
+    generatedAt?: Date;
+}
+export interface Enriched {
+    body: string;
+    tokens: number;
+}
+/** Rough token count: ~4 characters per token for English prose. */
+export declare function estimateTokens(text: string): number;
+export declare function hasFrontMatter(markdown: string): boolean;
+/**
+ * Builds the final Markdown body. A doc that already carries front matter
+ * (hand-written or stored docs usually do) is left exactly as it is, so the
+ * package never stacks a second block on top of an author's.
+ */
+export declare function enrich(doc: MarkdownDoc, meta: EnrichMeta): Enriched;
+/** A YAML front-matter block. Empty values are dropped; strings are JSON-quoted (valid YAML). */
+export declare function frontMatter(fields: Record<string, string | number | null | undefined>): string;
+/**
+ * A short "## Structured data" section from the page's JSON-LD, or null when
+ * nothing useful is there. Only well-known, flat facts are listed; the raw
+ * JSON is never dumped.
+ */
+export declare function jsonLdFacts(jsonLd: unknown[]): string | null;

package/dist/core/enrich.js

@@ -0,0 +1,155 @@
+"use strict";
+// Enrich: YAML front matter, a JSON-LD facts summary and a token estimate.
+//
+// EDGE-SAFE. No Node APIs.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTokens = estimateTokens;
+exports.hasFrontMatter = hasFrontMatter;
+exports.enrich = enrich;
+exports.frontMatter = frontMatter;
+exports.jsonLdFacts = jsonLdFacts;
+/** Rough token count: ~4 characters per token for English prose. */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function hasFrontMatter(markdown) {
+    return /^---\r?\n[\s\S]*?\r?\n---\r?\n/.test(markdown);
+}
+/**
+ * Builds the final Markdown body. A doc that already carries front matter
+ * (hand-written or stored docs usually do) is left exactly as it is, so the
+ * package never stacks a second block on top of an author's.
+ */
+function enrich(doc, meta) {
+    const markdown = doc.markdown.trim();
+    if (hasFrontMatter(markdown)) {
+        const body = markdown + "\n";
+        return { body, tokens: estimateTokens(body) };
+    }
+    const fm = frontMatter({
+        title: doc.title,
+        description: doc.description,
+        canonical: doc.canonical || meta.canonical,
+        source: meta.sourceUrl,
+        generated_at: (meta.generatedAt ?? new Date()).toISOString(),
+        generator: `agent-ready/${meta.source}`,
+        lang: doc.lang,
+    });
+    const facts = doc.jsonLd && doc.jsonLd.length ? jsonLdFacts(doc.jsonLd) : null;
+    const body = [fm, markdown, facts].filter(Boolean).join("\n\n") + "\n";
+    return { body, tokens: estimateTokens(body) };
+}
+/** A YAML front-matter block. Empty values are dropped; strings are JSON-quoted (valid YAML). */
+function frontMatter(fields) {
+    const lines = ["---"];
+    for (const [key, value] of Object.entries(fields)) {
+        if (value === null || value === undefined || value === "")
+            continue;
+        lines.push(`${key}: ${yamlScalar(value)}`);
+    }
+    lines.push("---");
+    return lines.join("\n");
+}
+function yamlScalar(value) {
+    if (typeof value === "number")
+        return String(value);
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    // Plain scalars are fine for URLs and ISO dates; quote everything else.
+    if (/^(https?:\/\/[^\s#]+|\d{4}-\d{2}-\d{2}T[\d:.]+Z|[a-z]{2,3}(-[A-Za-z]{2,4})?|agent-ready\/[a-z]+)$/.test(oneLine)) {
+        return oneLine;
+    }
+    return JSON.stringify(oneLine);
+}
+// JSON-LD types that describe the site chrome rather than the page's subject.
+const SKIP_TYPES = new Set([
+    "BreadcrumbList",
+    "WebSite",
+    "WebPage",
+    "SearchAction",
+    "SiteNavigationElement",
+    "ImageObject",
+    "ListItem",
+]);
+const MAX_FACT_OBJECTS = 5;
+/**
+ * A short "## Structured data" section from the page's JSON-LD, or null when
+ * nothing useful is there. Only well-known, flat facts are listed; the raw
+ * JSON is never dumped.
+ */
+function jsonLdFacts(jsonLd) {
+    const objects = [];
+    const visit = (node) => {
+        if (Array.isArray(node))
+            return node.forEach(visit);
+        if (!node || typeof node !== "object")
+            return;
+        const o = node;
+        if (Array.isArray(o["@graph"]))
+            o["@graph"].forEach(visit);
+        if (o["@type"])
+            objects.push(o);
+    };
+    jsonLd.forEach(visit);
+    const blocks = [];
+    for (const o of objects) {
+        const types = [].concat(o["@type"]).map(String);
+        if (types.every((t) => SKIP_TYPES.has(t)))
+            continue;
+        const facts = [];
+        const add = (label, v) => {
+            const s = text(v);
+            if (s)
+                facts.push([label, s]);
+        };
+        add("Name", o.name ?? o.headline);
+        add("Description", o.description);
+        add("URL", o.url);
+        add("Category", o.applicationCategory ?? o.category);
+        add("Operating system", o.operatingSystem);
+        add("Start", o.startDate);
+        add("End", o.endDate);
+        add("Location", pick(o.location, "name") ?? pick(pick(o.location, "address"), "addressLocality"));
+        add("Organizer", pick(o.organizer, "name"));
+        add("Author", pick(o.author, "name"));
+        add("Published", o.datePublished);
+        add("Modified", o.dateModified);
+        const offer = first(o.offers);
+        if (offer) {
+            const price = text(pick(offer, "price") ?? pick(offer, "lowPrice"));
+            const currency = text(pick(offer, "priceCurrency"));
+            if (price)
+                facts.push(["Price", currency ? `${price} ${currency}` : price]);
+        }
+        const rating = o.aggregateRating;
+        if (rating && typeof rating === "object") {
+            const value = text(rating.ratingValue);
+            const count = text(rating.reviewCount ?? rating.ratingCount);
+            if (value)
+                facts.push(["Rating", count ? `${value} (${count} reviews)` : value]);
+        }
+        if (!facts.length)
+            continue;
+        blocks.push([`### ${types.join(", ")}`, "", ...facts.map(([k, v]) => `- **${k}:** ${v}`)].join("\n"));
+        if (blocks.length >= MAX_FACT_OBJECTS)
+            break;
+    }
+    return blocks.length ? ["## Structured data", "", blocks.join("\n\n")].join("\n") : null;
+}
+function first(v) {
+    return Array.isArray(v) ? v[0] : v;
+}
+function pick(v, key) {
+    const o = first(v);
+    return o && typeof o === "object" ? o[key] : undefined;
+}
+function text(v) {
+    const x = first(v);
+    if (typeof x === "number")
+        return String(x);
+    if (typeof x !== "string")
+        return null;
+    const s = x.replace(/\s+/g, " ").trim();
+    if (!s)
+        return null;
+    return s.length > 300 ? s.slice(0, 297) + "..." : s;
+}

package/dist/core/llms.d.ts

@@ -0,0 +1,11 @@
+import type { LlmsEntry } from "./config";
+export interface BuildLlmsOptions {
+    site: string;
+    title: string;
+    summary?: string;
+    details?: string;
+    entries: LlmsEntry[];
+    /** Link to the `.md` variant of same-site pages. Default true. */
+    markdownLinks?: boolean;
+}
+export declare function buildLlmsTxt(opts: BuildLlmsOptions): string;

package/dist/core/llms.js

@@ -0,0 +1,71 @@
+"use strict";
+// Discover: build an llms.txt (https://llmstxt.org) from config entries.
+//
+//   # Title
+//
+//   > Summary
+//
+//   Details paragraphs
+//
+//   ## Section
+//
+//   - [Title](https://site/page.md): Description
+//
+//   ## Optional
+//
+//   - ...
+//
+// Links point at each page's `.md` variant when `markdownLinks` is on (the
+// default), so an agent reading llms.txt lands straight on Markdown.
+//
+// EDGE-SAFE. No Node APIs.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLlmsTxt = buildLlmsTxt;
+const detect_1 = require("./detect");
+function buildLlmsTxt(opts) {
+    const site = new URL(opts.site).origin;
+    const out = [`# ${oneLine(opts.title)}`];
+    if (opts.summary)
+        out.push(`> ${oneLine(opts.summary)}`);
+    if (opts.details)
+        out.push(opts.details.trim());
+    const sections = new Map();
+    const optional = [];
+    for (const e of opts.entries) {
+        const line = entryLine(e, site, opts.markdownLinks !== false);
+        if (!line)
+            continue;
+        if (e.optional) {
+            optional.push(line);
+            continue;
+        }
+        const name = oneLine(e.section || "Pages");
+        if (!sections.has(name))
+            sections.set(name, []);
+        sections.get(name).push(line);
+    }
+    sections.forEach((lines, name) => out.push(`## ${name}`, lines.join("\n")));
+    if (optional.length)
+        out.push("## Optional", optional.join("\n"));
+    return out.join("\n\n") + "\n";
+}
+function entryLine(e, site, markdownLinks) {
+    if (!e || !e.title || !e.url)
+        return null;
+    let url;
+    try {
+        url = new URL(e.url, site);
+    }
+    catch {
+        return null;
+    }
+    if (markdownLinks && e.markdown !== false && url.origin === site && !/\.[a-z0-9]+$/i.test(url.pathname)) {
+        url.pathname = (0, detect_1.mdUrlPath)(url.pathname.replace(/\/+$/, "") || "/");
+    }
+    const title = oneLine(e.title).replace(/[[\]]/g, "");
+    const desc = e.description ? `: ${oneLine(e.description)}` : "";
+    return `- [${title}](${url.href})${desc}`;
+}
+function oneLine(s) {
+    return s.replace(/\s+/g, " ").trim();
+}

package/dist/core/report.d.ts

@@ -0,0 +1,15 @@
+import type { HitEvent } from "./config";
+export interface ReporterOptions {
+    /** The venture's dashboard key. */
+    key: string;
+    /** Ingest URL that receives { key, event }. */
+    endpoint: string;
+    /** Give up after this long. Default 2000 ms. */
+    timeoutMs?: number;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+}
+/** An `onHit` that sends each event to the dashboard. */
+export declare function reporter(opts: ReporterOptions): (event: HitEvent) => Promise<void>;
+/** A reporter from env (AGENT_READY_KEY + AGENT_READY_ENDPOINT), or null when either is missing. */
+export declare function reporterFromEnv(env: Record<string, string | undefined>): ((event: HitEvent) => Promise<void>) | null;

package/dist/core/report.js

@@ -0,0 +1,46 @@
+"use strict";
+// Measure, the easy way: send every agent visit to a dashboard with one key
+// (changes/agent-ready-engine, "easy setup"). Replaces writing an `onHit`.
+//
+//   AGENT_READY_KEY=ar_live_xxx            (the venture's key)
+//   AGENT_READY_ENDPOINT=https://.../hits  (the dashboard's ingest URL)
+//
+// `reporter()` returns an `onHit` that POSTs { key, event } as JSON, with a
+// short timeout and keepalive. Fire-and-forget like every `onHit`: it never
+// throws and the response never waits for it.
+//
+// EDGE-SAFE. No Node APIs.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reporter = reporter;
+exports.reporterFromEnv = reporterFromEnv;
+/** An `onHit` that sends each event to the dashboard. */
+function reporter(opts) {
+    const f = opts.fetch ?? fetch;
+    return async (event) => {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), opts.timeoutMs ?? 2000);
+        try {
+            await f(opts.endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${opts.key}` },
+                body: JSON.stringify({ key: opts.key, event }),
+                keepalive: true,
+                signal: ctl.signal,
+            });
+        }
+        catch {
+            // A dashboard outage must never touch the agent's response.
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+/** A reporter from env (AGENT_READY_KEY + AGENT_READY_ENDPOINT), or null when either is missing. */
+function reporterFromEnv(env) {
+    const key = env.AGENT_READY_KEY?.trim();
+    const endpoint = env.AGENT_READY_ENDPOINT?.trim();
+    if (!key || !endpoint || !/^https?:\/\//.test(endpoint))
+        return null;
+    return reporter({ key, endpoint });
+}

package/dist/core/resolve.d.ts

@@ -0,0 +1,43 @@
+import { type MarkdownDoc, type ResolvedAgentReadyConfig } from "./config";
+import type { ConvertResult } from "./convert";
+export interface ResolveInput {
+    /** Normalised page path, e.g. "/tool/notion". */
+    path: string;
+    /** Query string to keep, "" or "?a=b". */
+    search: string;
+    request: Request;
+}
+export interface Resolved {
+    /** Which step produced the doc; null = nothing usable (doc is null). */
+    source: "native" | "stored" | "convert" | null;
+    doc: MarkdownDoc | null;
+    /** Absolute URL of the HTML page the doc stands for. */
+    sourceUrl: string;
+    /** The origin's HTML response when convert fetched one but couldn't use it. */
+    html: {
+        status: number;
+        contentType: string;
+        body: string;
+    } | null;
+    /** Origin status when the convert step reached the origin. */
+    originStatus: number | null;
+}
+export interface ResolveDeps {
+    fetch?: typeof fetch;
+    convert?: (html: string, opts: {
+        url: string;
+        minChars?: number;
+    }) => ConvertResult | null;
+}
+export declare function resolveMarkdown(cfg: ResolvedAgentReadyConfig, input: ResolveInput, deps?: ResolveDeps): Promise<Resolved>;
+/**
+ * Where the converter fetches HTML from: the host the request came in on, so
+ * staging converts staging and a test host converts itself. `*.localhost`
+ * names become `localhost` (Node's resolver doesn't map them everywhere).
+ */
+export declare function defaultFetchOrigin(request: Request, site: string): string;
+/**
+ * "/tool/:slug" -> { slug }, "/docs/*" -> { "*": rest }. Exact otherwise.
+ * Returns null when the path doesn't match.
+ */
+export declare function matchPattern(pattern: string, path: string): Record<string, string> | null;