npm - agent-readiness - Versions diffs - 0.4.0 - Mend

agent-readiness 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/lib/core.mjs ADDED Viewed

@@ -0,0 +1,971 @@
+import { writeFile, mkdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parse } from 'node-html-parser'
+const UA = 'agent-ready/0.4 (+https://github.com/VeldinS/agent-ready)'
+// ---------------------------------------------------------------------------
+// Fetching / crawling
+// ---------------------------------------------------------------------------
+async function tryFetch(url, { timeout = 8000, maxBytes = 5 * 1024 * 1024, signal } = {}) {
+  const ctrl = new AbortController()
+  const t = setTimeout(() => ctrl.abort(), timeout)
+  // Honor an optional caller signal (e.g. a server-route wall-clock deadline) on top of the
+  // per-fetch timeout, so the whole crawl can be cancelled — not just each individual request.
+  const onAbort = () => ctrl.abort()
+  if (signal) {
+    if (signal.aborted) ctrl.abort()
+    else signal.addEventListener('abort', onAbort, { once: true })
+  }
+  try {
+    const res = await fetch(url, { headers: { 'user-agent': UA }, redirect: 'follow', signal: ctrl.signal })
+    if (!res.ok) return null
+    const len = Number(res.headers.get('content-length'))
+    if (Number.isFinite(len) && len > maxBytes) return null // refuse oversized before reading
+    if (!res.body || typeof res.body.getReader !== 'function') return await res.text()
+    // Stream with a hard byte cap so a huge/streaming body can't OOM the process.
+    const reader = res.body.getReader()
+    const decoder = new TextDecoder('utf-8')
+    let received = 0
+    let out = ''
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      received += value.byteLength
+      if (received > maxBytes) {
+        try {
+          await reader.cancel()
+        } catch {
+          /* ignore */
+        }
+        ctrl.abort()
+        break // keep the truncated head we already have
+      }
+      out += decoder.decode(value, { stream: true })
+    }
+    out += decoder.decode()
+    return out
+  } catch {
+    return null
+  } finally {
+    clearTimeout(t)
+    if (signal) signal.removeEventListener('abort', onAbort)
+  }
+}
+// A SPA / catch-all that 200s every path serves index.html for /llms.txt etc. — don't count HTML as a real file.
+function looksLikeHtml(s) {
+  const h = (s || '').replace(/^/, '').trimStart()
+  return /^(<!doctype html|<html[\s>])/i.test(h)
+}
+// Run async tasks with a concurrency cap (keeps multi-page crawls polite + fast).
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length)
+  let i = 0
+  const count = items.length === 0 ? 0 : Math.max(1, Math.min(limit, items.length))
+  const workers = Array.from({ length: count }, async () => {
+    while (i < items.length) {
+      const idx = i++
+      out[idx] = await fn(items[idx], idx)
+    }
+  })
+  await Promise.all(workers)
+  return out
+}
+function decodeXml(s) {
+  return s
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+}
+function parseSitemapLocs(xml) {
+  const locs = []
+  for (const m of xml.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/gi)) locs.push(decodeXml(m[1].trim()))
+  return locs
+}
+const NON_PAGE = /\.(jpg|jpeg|png|gif|svg|webp|ico|css|js|mjs|json|xml|pdf|zip|gz|rss|atom|mp4|mp3|woff2?|ttf)(\?|#|$)/i
+const TRACKING = /^(ref|ref_|utm_[a-z]+|fbclid|gclid|mc_cid|mc_eid|igshid|_hsenc|_hsmi)$/i
+// Titles that signal an error/permission page we should not list as real content.
+const ERROR_TITLE = /\b(40[0-9]|not found|page not found|permission error|access denied|forbidden|do not have permission|error)\b/i
+function sameHost(a, b) {
+  try {
+    return new URL(a).host === new URL(b).host
+  } catch {
+    return false
+  }
+}
+// Strip tracking params + fragment so ref/utm-tagged duplicates collapse to one entry.
+function cleanUrl(raw) {
+  try {
+    const u = new URL(raw)
+    u.hash = ''
+    for (const k of [...u.searchParams.keys()]) if (TRACKING.test(k)) u.searchParams.delete(k)
+    return u.toString()
+  } catch {
+    return raw
+  }
+}
+// Collect candidate page URLs from a sitemap. Bounded BFS so nested sitemap-index
+// files (and CDN-hosted children) still yield pages, without runaway crawling.
+async function collectSitemapUrls(base, sitemapRaw, cap = 25, signal) {
+  if (!sitemapRaw) return []
+  const seen = new Set()
+  const out = []
+  const addPage = (u) => {
+    if (!/^https?:\/\//i.test(u) || NON_PAGE.test(u)) return
+    if (base && !sameHost(u, base)) return
+    const c = cleanUrl(u)
+    if (seen.has(c)) return
+    seen.add(c)
+    out.push(c)
+  }
+  const MAX_SITEMAP_FETCH = 5
+  let fetches = 0
+  const queue = [sitemapRaw]
+  while (queue.length && out.length < cap) {
+    const doc = queue.shift()
+    if (/<sitemapindex/i.test(doc)) {
+      // children are other sitemaps — may legitimately live on another host (CDN).
+      const children = parseSitemapLocs(doc).slice(0, MAX_SITEMAP_FETCH - fetches)
+      const raws = await mapLimit(children, 3, (u) => {
+        fetches++
+        return tryFetch(u, { timeout: 7000, signal })
+      })
+      for (const r of raws) if (r) queue.push(r)
+    } else {
+      for (const u of parseSitemapLocs(doc)) {
+        addPage(u)
+        if (out.length >= cap) break
+      }
+    }
+  }
+  return out
+}
+function extractPageMeta(html) {
+  try {
+    const root = parse(html)
+    const title = clean(root.querySelector('title')?.text || '')
+    let description = ''
+    for (const m of root.querySelectorAll('meta')) {
+      if ((m.getAttribute('name') || '').toLowerCase() === 'description') {
+        description = clean(m.getAttribute('content') || '')
+        if (description) break
+      }
+    }
+    const h1 = clean(root.querySelector('h1')?.text || '')
+    return { title, description, h1 }
+  } catch {
+    return { title: '', description: '', h1: '' }
+  }
+}
+function pathOf(url, base) {
+  try {
+    const u = new URL(url, base || undefined)
+    return (u.pathname || '/') + (u.search || '')
+  } catch {
+    return url
+  }
+}
+// Same-origin links from the home page — fallback page source when there's no sitemap.
+function sameOriginLinks(home, base, cap = 20) {
+  let root
+  try {
+    root = parse(home || '')
+  } catch {
+    return []
+  }
+  const out = []
+  const seen = new Set()
+  for (const a of root.querySelectorAll('a[href]')) {
+    let h = (a.getAttribute('href') || '').trim()
+    if (!h || /^(#|mailto:|tel:|javascript:)/i.test(h)) continue
+    let url
+    if (/^https?:\/\//i.test(h)) {
+      if (!sameHost(h, base)) continue
+      url = h
+    } else if (h.startsWith('/')) {
+      url = base + h
+    } else {
+      continue
+    }
+    url = cleanUrl(url)
+    if (NON_PAGE.test(url) || seen.has(url) || url === base || url === base + '/') continue
+    seen.add(url)
+    out.push(url)
+    if (out.length >= cap) break
+  }
+  return out
+}
+// Fetch each discovered page and derive a one-line summary for llms.txt.
+async function fetchPageSummaries(urls, base, fetchCap = 18, signal) {
+  const targets = urls.slice(0, fetchCap)
+  const fetched = await mapLimit(targets, 8, async (url) => {
+    const html = await tryFetch(url, { timeout: 7000, signal })
+    if (!html) return null
+    const meta = extractPageMeta(html)
+    const title = oneLine(meta.title || meta.h1 || pathOf(url, base))
+    if (ERROR_TITLE.test(title)) return null // skip 404/permission/error pages
+    return {
+      url,
+      path: pathOf(url, base),
+      title,
+      summary: oneLine(meta.description || meta.h1 || '')
+    }
+  })
+  return fetched.filter(Boolean)
+}
+const isXmlSitemap = (s) => !!s && /(<urlset|<sitemapindex|<\?xml)/i.test(s)
+export async function crawl(target, { signal } = {}) {
+  const u = new URL(/^https?:\/\//i.test(target) ? target : 'https://' + target)
+  const base = u.origin // site-root files (llms/robots/sitemap) live at the ORIGIN, not the scanned path
+  const pageUrl = u.href
+  const home = await tryFetch(pageUrl, { signal })
+  if (home == null) throw new Error(`Could not fetch ${pageUrl}`)
+  const [llmsRaw, robotsRaw, sitemapRaw] = await Promise.all([
+    tryFetch(base + '/llms.txt', { signal }),
+    tryFetch(base + '/robots.txt', { signal }),
+    tryFetch(base + '/sitemap.xml', { signal })
+  ])
+  // Reject SPA catch-all HTML masquerading as these files so the score stays honest.
+  const llmsTxt = looksLikeHtml(llmsRaw) ? null : llmsRaw
+  const robots = looksLikeHtml(robotsRaw) ? null : robotsRaw
+  let sitemap = isXmlSitemap(sitemapRaw) ? sitemapRaw : null
+  // Honor a "Sitemap:" directive in robots.txt when the conventional path is absent.
+  if (!sitemap && robots) {
+    const declared = [...robots.matchAll(/^\s*sitemap:\s*(\S+)/gim)].map((m) => m[1])
+    for (const sm of declared.slice(0, 3)) {
+      const raw = await tryFetch(sm, { timeout: 7000, signal })
+      if (isXmlSitemap(raw)) {
+        sitemap = raw
+        break
+      }
+    }
+  }
+  let urls = await collectSitemapUrls(base, sitemap, 25, signal)
+  if (urls.length === 0) urls = sameOriginLinks(home, base) // no sitemap → fall back to home links
+  const pages = await fetchPageSummaries(urls, base, 18, signal)
+  return { base, home, llmsTxt, robots, sitemap, pages }
+}
+export async function crawlLocal(path) {
+  const home = await readFile(path, 'utf8')
+  return { base: '', home, llmsTxt: null, robots: null, sitemap: null, pages: null }
+}
+// ---------------------------------------------------------------------------
+// Small string helpers
+// ---------------------------------------------------------------------------
+function clean(s) {
+  return String(s == null ? '' : s)
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+function oneLine(s, max = 200) {
+  const c = clean(s)
+  return c.length > max ? c.slice(0, max - 1).trimEnd() + '…' : c
+}
+function kebab(s) {
+  const k = String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64)
+  return k || 'tool'
+}
+function lastSegment(p) {
+  const parts = String(p || '')
+    .split(/[?#]/)[0]
+    .split('/')
+    .filter(Boolean)
+  return parts.length ? parts[parts.length - 1] : ''
+}
+function uniqName(base, used) {
+  let name = base
+  let n = 2
+  while (used.has(name)) name = `${base}-${n++}`
+  used.add(name)
+  return name
+}
+function abs(url, base) {
+  if (!url) return url
+  if (/^https?:\/\//i.test(url)) return url
+  if (base && url.startsWith('/')) return base + url
+  return url
+}
+// A link safe to emit into llms.txt: absolutised, with dangerous schemes rejected.
+function safeHref(url, base) {
+  const a = abs(url, base)
+  if (!a) return null
+  if (/^\s*(javascript|data|vbscript|file):/i.test(a)) return null
+  return a
+}
+// Escape Markdown link-significant characters in crawled page titles/summaries so a
+// hostile title like "x](http://evil)" can't hijack the generated link.
+function mdText(s, max = 200) {
+  return oneLine(s, max).replace(/[[\]()\\`]/g, (m) => '\\' + m)
+}
+function escHtml(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+// ---------------------------------------------------------------------------
+// Extraction (analyze) — node-html-parser backed
+// ---------------------------------------------------------------------------
+const SKIP_INPUT_TYPES = new Set(['hidden', 'submit', 'button', 'image', 'reset'])
+function schemaType(rawType) {
+  const t = String(rawType || '').toLowerCase()
+  if (t === 'number' || t === 'range') return 'number'
+  if (t === 'checkbox') return 'boolean'
+  return 'string'
+}
+function findLabel(root, el) {
+  try {
+    const id = el.getAttribute('id')
+    if (id) {
+      const lbl = root.querySelector(`label[for="${id}"]`)
+      if (lbl) return clean(lbl.text)
+    }
+    const wrap = el.closest && el.closest('label')
+    if (wrap) return clean(wrap.text)
+  } catch {
+    /* selectors with odd ids can throw — ignore */
+  }
+  return ''
+}
+function extractForms(root) {
+  const forms = []
+  for (const form of root.querySelectorAll('form')) {
+    const action = form.getAttribute('action') || '/'
+    const method = (form.getAttribute('method') || 'get').toUpperCase()
+    const inputs = []
+    for (const el of form.querySelectorAll('input, select, textarea')) {
+      const name = el.getAttribute('name')
+      if (!name) continue
+      const tag = (el.rawTagName || '').toLowerCase()
+      const rawType = tag === 'textarea' ? 'textarea' : tag === 'select' ? 'select' : (el.getAttribute('type') || 'text').toLowerCase()
+      if (SKIP_INPUT_TYPES.has(rawType)) continue
+      let options
+      if (tag === 'select') {
+        options = el
+          .querySelectorAll('option')
+          .map((o) => o.getAttribute('value') ?? clean(o.text))
+          .filter((v) => v !== '' && v != null)
+      }
+      inputs.push({
+        name,
+        type: rawType,
+        schemaType: schemaType(rawType),
+        required: el.hasAttribute('required'),
+        placeholder: el.getAttribute('placeholder') || '',
+        label: findLabel(root, el),
+        options
+      })
+    }
+    forms.push({ action, method, inputs })
+  }
+  return forms
+}
+function isSearchForm(f) {
+  if (f.method !== 'GET') return false
+  if (/search/i.test(f.action || '')) return true
+  return f.inputs.some((i) => i.type === 'search' || ['q', 'query', 's', 'search'].includes((i.name || '').toLowerCase()))
+}
+// Intent table for inferring WebMCP tools from JS-driven buttons/links (no <form>).
+const INTENTS = [
+  {
+    intent: 'search',
+    name: 'search-site',
+    test: (h) => /\bsearch\b/.test(h), // bare "find" matched "Find a store" etc. — too noisy
+    description: 'Search this site and return matching results.',
+    props: { query: { type: 'string', description: 'Search query' } },
+    required: ['query'],
+    readOnly: true,
+    method: 'GET'
+  },
+  {
+    intent: 'login',
+    name: 'log-in',
+    test: (h) => /\blog[\s-]?in\b|\bsign[\s-]?in\b|\bsign on\b/.test(h),
+    description: 'Log in to an existing account.',
+    props: { email: { type: 'string', description: 'Account email' }, password: { type: 'string', description: 'Account password' } },
+    required: ['email', 'password'],
+    readOnly: false,
+    method: 'POST'
+  },
+  {
+    intent: 'signup',
+    name: 'sign-up',
+    test: (h) => /\bsign[\s-]?up\b|\bregister\b|\bcreate (an )?account\b|\bget started\b|\bjoin free\b|\bstart (your )?free\b/.test(h),
+    description: 'Create a new account.',
+    props: { email: { type: 'string', description: 'Email address' }, password: { type: 'string', description: 'Chosen password' } },
+    required: ['email'],
+    readOnly: false,
+    method: 'POST'
+  },
+  {
+    intent: 'add-to-cart',
+    name: 'add-to-cart',
+    test: (h) => /\badd to (cart|bag|basket)\b|\bbuy now\b/.test(h),
+    description: 'Add a product to the shopping cart.',
+    props: { productId: { type: 'string', description: 'ID of the product to add' }, quantity: { type: 'number', description: 'Quantity', default: 1 } },
+    required: ['productId'],
+    readOnly: false,
+    method: 'POST'
+  },
+  {
+    intent: 'checkout',
+    name: 'checkout',
+    test: (h) => /\bcheckout\b|\bplace order\b|\bcomplete (order|purchase)\b|\bpay now\b/.test(h),
+    description: 'Proceed to checkout and place the order.',
+    props: {},
+    required: [],
+    readOnly: false,
+    method: 'POST'
+  },
+  {
+    intent: 'contact',
+    name: 'contact',
+    test: (h) => /\bcontact( us)?\b|\bget in touch\b|\btalk to (us|sales)\b|\bbook a (demo|call)\b|\brequest a demo\b/.test(h),
+    description: 'Send a contact or sales enquiry.',
+    props: { name: { type: 'string' }, email: { type: 'string' }, message: { type: 'string', description: 'Your message' } },
+    required: ['email', 'message'],
+    readOnly: false,
+    method: 'POST'
+  },
+  {
+    intent: 'subscribe',
+    name: 'subscribe',
+    test: (h) => /\bsubscribe\b|\bnewsletter\b|\bmailing list\b|\bnotify me\b|\bstay (in the loop|updated)\b/.test(h),
+    description: 'Subscribe an email address to the newsletter.',
+    props: { email: { type: 'string', description: 'Email address to subscribe' } },
+    required: ['email'],
+    readOnly: false,
+    method: 'POST'
+  }
+]
+function formIntentSet(forms) {
+  const s = new Set()
+  for (const f of forms) {
+    const pw = f.inputs.filter((i) => i.type === 'password')
+    if (pw.length) {
+      // A password form covers ONE auth intent — mark the one it actually is so the
+      // complementary action (e.g. a separate "Sign up" link) stays inferable.
+      const hay = (f.action + ' ' + f.inputs.map((i) => `${i.name} ${i.label} ${i.placeholder}`).join(' ')).toLowerCase()
+      const looksSignup = pw.length >= 2 || /register|sign[\s-]?up|create[\s-]?account|create your account|\bjoin\b/.test(hay)
+      s.add(looksSignup ? 'signup' : 'login')
+    }
+    if (isSearchForm(f)) s.add('search')
+    const emails = f.inputs.filter((i) => i.type === 'email')
+    if (!pw.length && emails.length === 1 && f.inputs.length <= 2) s.add('subscribe')
+  }
+  return s
+}
+function insideForm(el) {
+  try {
+    return !!(el.closest && el.closest('form'))
+  } catch {
+    return false
+  }
+}
+function inferActions(root, forms) {
+  const covered = formIntentSet(forms)
+  const candidates = []
+  // Elements inside a <form> are already represented by that form's tool — skip them.
+  for (const el of root.querySelectorAll('a[href]')) {
+    if (insideForm(el)) continue
+    candidates.push({
+      text: clean(el.text),
+      href: el.getAttribute('href'),
+      aria: el.getAttribute('aria-label'),
+      id: el.getAttribute('id')
+    })
+  }
+  for (const el of root.querySelectorAll('button, input[type=submit], input[type=button], [role=button]')) {
+    if (insideForm(el)) continue
+    const tag = (el.rawTagName || '').toLowerCase()
+    const text = tag === 'input' ? el.getAttribute('value') || '' : clean(el.text)
+    candidates.push({ text: clean(text), href: null, aria: el.getAttribute('aria-label'), id: el.getAttribute('id') })
+  }
+  const actions = []
+  const usedIntents = new Set()
+  for (const c of candidates) {
+    if (actions.length >= 8) break
+    // Match only on SHORT, button-like text + aria-label. Matching href/id (or long
+    // headline text) turned article links like ".../instant-checkout" into fake tools.
+    const label = clean([c.text, c.aria].filter(Boolean).join(' '))
+    const words = label.split(/\s+/).filter(Boolean)
+    if (!label || words.length > 5) continue
+    const hay = label.toLowerCase()
+    for (const intent of INTENTS) {
+      if (covered.has(intent.intent) || usedIntents.has(intent.intent)) continue
+      if (!intent.test(hay)) continue
+      usedIntents.add(intent.intent)
+      actions.push({
+        name: intent.name,
+        intent: intent.intent,
+        description: intent.description,
+        props: intent.props,
+        required: intent.required,
+        readOnly: intent.readOnly,
+        endpoint: c.href && /^(https?:\/\/|\/)/i.test(c.href) ? c.href : null,
+        method: intent.method
+      })
+      break
+    }
+  }
+  return actions
+}
+function pagesFromHome(root, base) {
+  const pages = []
+  const seen = new Set()
+  for (const a of root.querySelectorAll('a[href]')) {
+    let h = (a.getAttribute('href') || '').trim()
+    if (!h || /^(#|mailto:|tel:|javascript:)/i.test(h)) continue
+    let url
+    let path
+    if (/^https?:\/\//i.test(h)) {
+      if (base && !sameHost(h, base)) continue
+      url = h
+      path = pathOf(h, base)
+    } else if (h.startsWith('/')) {
+      url = base ? base + h : h
+      path = h.split(/[?#]/)[0]
+    } else {
+      continue
+    }
+    if (NON_PAGE.test(url)) continue
+    if (seen.has(url)) continue
+    seen.add(url)
+    pages.push({ url, path, title: clean(a.text) || path, summary: '' })
+    if (pages.length >= 25) break
+  }
+  return pages
+}
+export function analyze({ base = '', home = '', llmsTxt = null, robots = null, sitemap = null, pages = null }) {
+  let root
+  try {
+    root = parse(home || '')
+  } catch {
+    root = parse('')
+  }
+  const title = clean(root.querySelector('title')?.text || '')
+  let description = ''
+  let hasOg = false
+  for (const m of root.querySelectorAll('meta')) {
+    const name = (m.getAttribute('name') || '').toLowerCase()
+    const prop = (m.getAttribute('property') || '').toLowerCase()
+    if (!description && name === 'description') description = clean(m.getAttribute('content') || '')
+    if (!hasOg && prop.startsWith('og:')) hasOg = true
+  }
+  let hasJsonLd = false
+  for (const s of root.querySelectorAll('script')) {
+    if ((s.getAttribute('type') || '').toLowerCase().includes('ld+json')) {
+      hasJsonLd = true
+      break
+    }
+  }
+  let hasCanonical = false
+  let canonicalUrl = ''
+  for (const l of root.querySelectorAll('link')) {
+    const rel = (l.getAttribute('rel') || '').toLowerCase()
+    if (rel.split(/\s+/).includes('canonical')) {
+      hasCanonical = true
+      canonicalUrl = l.getAttribute('href') || ''
+      break
+    }
+  }
+  const htmlLang = clean(root.querySelector('html')?.getAttribute('lang') || '')
+  // Require the imperative API (or our generated scaffold filename) — a bare "webmcp"
+  // substring false-passed sites that merely had e.g. id="webmcp".
+  const hasWebMcp = /(navigator|document)\.modelContext|modelContext\s*\.\s*registerTool|webmcp\.tools/i.test(home)
+  const landmarks = ['main', 'nav', 'header', 'footer'].filter((t) => root.querySelector(t))
+  const h1 = root.querySelectorAll('h1').length
+  const imgs = root.querySelectorAll('img')
+  const imgTotal = imgs.length
+  const imgWithAlt = imgs.filter((i) => i.hasAttribute('alt')).length
+  const altCoverage = imgTotal === 0 ? 1 : imgWithAlt / imgTotal
+  const altPass = imgTotal === 0 || altCoverage >= 0.8
+  const forms = extractForms(root)
+  const actions = inferActions(root, forms)
+  // Empty (not just null) means the crawl found/fetched nothing usable → still try home links.
+  const pageList = Array.isArray(pages) && pages.length ? pages : pagesFromHome(root, base)
+  return {
+    base,
+    title,
+    description,
+    htmlLang,
+    hasCanonical,
+    canonicalUrl,
+    hasJsonLd,
+    hasOg,
+    hasWebMcp,
+    landmarks,
+    h1,
+    imgTotal,
+    imgWithAlt,
+    altCoverage,
+    altPass,
+    hasLlmsTxt: !!(llmsTxt && llmsTxt.trim().length > 20),
+    hasSitemap: !!sitemap,
+    hasRobots: !!robots,
+    forms,
+    actions,
+    pages: pageList
+  }
+}
+// ---------------------------------------------------------------------------
+// Scoring — 9 weighted checks, weights sum to 100
+// ---------------------------------------------------------------------------
+export function score(a) {
+  const altPct = Math.round((a.altCoverage ?? 1) * 100)
+  const checks = [
+    {
+      id: 'llms_txt',
+      label: 'llms.txt present',
+      weight: 22,
+      pass: a.hasLlmsTxt,
+      fix: 'Add /llms.txt so agents get a clean, token-cheap map of your site (generated below).'
+    },
+    {
+      id: 'webmcp',
+      label: 'WebMCP tools (document.modelContext)',
+      weight: 22,
+      pass: a.hasWebMcp,
+      fix: 'Expose your key actions as WebMCP tools so agents can ACT, not just scrape (scaffold generated below).'
+    },
+    {
+      id: 'structured',
+      label: 'Structured data (JSON-LD / OpenGraph)',
+      weight: 13,
+      pass: a.hasJsonLd || a.hasOg,
+      fix: 'Add schema.org JSON-LD and OpenGraph tags for machine-readable meaning (snippet generated below).'
+    },
+    {
+      id: 'semantics',
+      label: 'Semantic landmarks + an H1',
+      weight: 13,
+      pass: a.landmarks.length >= 2 && a.h1 >= 1,
+      fix: 'Use <main>/<nav>/<header> landmarks and at least one <h1> so agents can parse structure.'
+    },
+    {
+      id: 'metadata',
+      label: 'Title + meta description',
+      weight: 10,
+      pass: !!(a.title && a.description),
+      fix: 'Add a <title> and <meta name="description"> so an agent knows what the page is.'
+    },
+    {
+      id: 'discovery',
+      label: 'robots.txt + sitemap.xml',
+      weight: 8,
+      pass: a.hasRobots && a.hasSitemap,
+      fix: 'Add robots.txt and sitemap.xml for crawl + discovery.'
+    },
+    {
+      id: 'canonical',
+      label: 'Canonical URL (<link rel="canonical">)',
+      weight: 4,
+      pass: a.hasCanonical,
+      fix: 'Add <link rel="canonical" href="..."> so agents dedupe URLs to one authoritative address.'
+    },
+    {
+      id: 'lang',
+      label: 'Document language (<html lang>)',
+      weight: 4,
+      pass: !!a.htmlLang,
+      fix: 'Set <html lang="en"> (or your language) so agents know the content language.'
+    },
+    {
+      id: 'alt_text',
+      label: `Image alt-text coverage${a.imgTotal ? ` (${a.imgWithAlt}/${a.imgTotal}, ${altPct}%)` : ''}`,
+      weight: 4,
+      pass: a.altPass,
+      fix: 'Add alt text to images (alt="..."), or alt="" for decorative ones, so agents understand visuals.'
+    }
+  ]
+  const total = checks.reduce((s, c) => s + (c.pass ? c.weight : 0), 0)
+  return { total, checks }
+}
+// ---------------------------------------------------------------------------
+// Generators
+// ---------------------------------------------------------------------------
+export function buildLlmsTxt(a) {
+  const lines = []
+  lines.push(`# ${oneLine(a.title || a.base || 'Site', 120)}`)
+  if (a.description) lines.push('', `> ${oneLine(a.description)}`)
+  const pages = (a.pages || []).filter((p) => p && (p.url || p.path))
+  if (pages.length) {
+    const seen = new Set()
+    const rows = []
+    for (const p of pages) {
+      const link = safeHref(p.url || p.path, a.base)
+      if (!link || seen.has(link)) continue
+      seen.add(link)
+      const label = mdText(p.title || p.path || link, 100)
+      const summary = mdText(p.summary || '')
+      rows.push(summary ? `- [${label}](${link}): ${summary}` : `- [${label}](${link})`)
+    }
+    if (rows.length) lines.push('', '## Pages', ...rows)
+  }
+  // Only real <form> endpoints go here — inferred (guessed) action endpoints would be
+  // misleading in an index file; they live in the WebMCP scaffold (with TODO hedges).
+  const acts = []
+  for (const f of a.forms) {
+    const url = safeHref(f.action, a.base)
+    if (!url) continue
+    const label = isSearchForm(f) ? 'Search' : `Submit ${lastSegment(f.action) || 'form'}`
+    const fields = f.inputs.map((i) => i.name).join(', ')
+    acts.push({ label, url, note: `${f.method} form${fields ? `, fields: ${fields}` : ''}` })
+  }
+  if (acts.length) {
+    lines.push('', '## Actions')
+    const seen = new Set()
+    for (const x of acts) {
+      const key = `${x.label}|${x.url}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      lines.push(`- [${mdText(x.label, 80)}](${x.url}): ${mdText(x.note)}`)
+    }
+  }
+  lines.push('', '<!-- Generated by agent-ready • https://github.com/VeldinS/agent-ready -->')
+  return lines.join('\n') + '\n'
+}
+// Assign an OWN enumerable property even for keys like "__proto__" (which plain
+// bracket-assignment would route to the prototype, silently dropping the field).
+function setProp(obj, key, value) {
+  Object.defineProperty(obj, key, { value, enumerable: true, writable: true, configurable: true })
+}
+function propsFor(inputsOrProps, required) {
+  // forms pass an inputs[] array; inferred actions pass a ready-made props object.
+  if (Array.isArray(inputsOrProps)) {
+    const props = {}
+    const req = []
+    for (const i of inputsOrProps) {
+      if (!i.name) continue
+      const p = { type: i.schemaType }
+      const desc = i.label || i.placeholder
+      if (desc) p.description = oneLine(desc, 120)
+      if (i.options && i.options.length) p.enum = i.options
+      setProp(props, i.name, p)
+      if (i.required) req.push(i.name)
+    }
+    return { props, required: req }
+  }
+  return { props: inputsOrProps || {}, required: required || [] }
+}
+function toolFromForm(f, used) {
+  const search = isSearchForm(f)
+  const baseName = search ? 'search-site' : `submit-${lastSegment(f.action) || 'form'}`
+  const name = uniqName(kebab(baseName), used)
+  const { props, required } = propsFor(f.inputs)
+  return {
+    name,
+    description: search ? 'Search this site and return matching results.' : `Submit the ${f.action} form via ${f.method}.`,
+    props,
+    required,
+    readOnly: search,
+    endpoint: f.action || '/',
+    method: search ? 'GET' : f.method || 'POST'
+  }
+}
+function toolFromAction(ac, used) {
+  const name = uniqName(kebab(ac.name), used)
+  const { props, required } = propsFor(ac.props, ac.required)
+  return {
+    name,
+    description: ac.description,
+    props,
+    required,
+    readOnly: ac.readOnly,
+    endpoint: ac.endpoint,
+    method: ac.method || 'POST'
+  }
+}
+function renderTool(t) {
+  const L = []
+  L.push('  {')
+  L.push(`    name: ${JSON.stringify(t.name)},`)
+  L.push(`    description: ${JSON.stringify(t.description)},`)
+  if (t.props && Object.keys(t.props).length) {
+    L.push('    inputSchema: {')
+    L.push('      type: "object",')
+    L.push(`      properties: ${JSON.stringify(t.props)},`)
+    L.push(`      required: ${JSON.stringify(t.required || [])}`)
+    L.push('    },')
+  }
+  if (t.readOnly) L.push('    annotations: { readOnlyHint: true },')
+  L.push('    async execute(input) {')
+  if (t.endpoint) {
+    if (String(t.method).toUpperCase() === 'GET') {
+      L.push(`      // TODO: confirm this maps to your real GET ${t.endpoint} handler`)
+      L.push(`      const url = new URL(${JSON.stringify(t.endpoint)}, location.href);`)
+      L.push('      for (const [k, v] of Object.entries(input || {})) url.searchParams.set(k, v);')
+      L.push('      const res = await fetch(url, { method: "GET", headers: { accept: "application/json" } });')
+    } else {
+      L.push(`      // TODO: confirm this maps to your real ${t.method} ${t.endpoint} handler`)
+      L.push(`      const res = await fetch(${JSON.stringify(t.endpoint)}, {`)
+      L.push(`        method: ${JSON.stringify(t.method)},`)
+      L.push('        headers: { "content-type": "application/json" },')
+      L.push('        body: JSON.stringify(input)')
+      L.push('      });')
+    }
+    L.push('      return { content: [{ type: "text", text: await res.text() }] };')
+  } else {
+    L.push(`      // TODO: wire this tool to your on-page "${t.name}" action.`)
+    L.push(`      return { content: [{ type: "text", text: ${JSON.stringify(`Not implemented: connect the ${t.name} tool to your handler.`)} }] };`)
+  }
+  L.push('    }')
+  L.push('  }')
+  return L.join('\n')
+}
+const EMPTY_TOOLS = `  // No <form> elements or obvious actions were detected on this page.
+  // Define your key actions as tools so agents can act on your site, e.g.:
+  // {
+  //   name: "search-site",
+  //   description: "Search this site and return matching results.",
+  //   inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+  //   annotations: { readOnlyHint: true },
+  //   async execute(input) {
+  //     const url = new URL("/search", location.href);
+  //     url.searchParams.set("q", input.query);
+  //     const res = await fetch(url);
+  //     return { content: [{ type: "text", text: await res.text() }] };
+  //   }
+  // }`
+export function buildWebMcp(a) {
+  const used = new Set()
+  const tools = []
+  for (const f of a.forms) tools.push(toolFromForm(f, used))
+  for (const ac of a.actions) tools.push(toolFromAction(ac, used))
+  const body = tools.length ? tools.map(renderTool).join(',\n') : EMPTY_TOOLS
+  return `// Generated by agent-ready — WebMCP tool scaffold.
+// Spec: https://webmachinelearning.github.io/webmcp/  •  https://github.com/webmachinelearning/webmcp
+// Load this on your site OVER HTTPS so AI agents can ACT on it, not just scrape it.
+// WebMCP exposes document.modelContext.registerTool() and requires a secure context.
+const AGENT_READY_TOOLS = [
+${body}
+];
+if (typeof document !== "undefined" && document.modelContext) {
+  const controller = new AbortController(); // abort controller.signal to unregister these tools
+  for (const tool of AGENT_READY_TOOLS) {
+    Promise.resolve(document.modelContext.registerTool(tool, { signal: controller.signal })).catch((err) =>
+      console.warn("agent-ready: could not register tool", tool.name, err)
+    );
+  }
+}
+`
+}
+export function buildStructuredData(a) {
+  const name = a.title || a.base || 'Your site'
+  const url = a.base || a.canonicalUrl || 'https://your-site.com'
+  const description = a.description || 'A short description of what this site is and does.'
+  const jsonld = { '@context': 'https://schema.org', '@type': 'WebSite', name, url, description }
+  // Escape "<" so a value containing "</script>" cannot break out of the inline JSON-LD block.
+  const jsonldSafe = JSON.stringify(jsonld, null, 2).replace(/</g, '\\u003c')
+  return `<!-- Generated by agent-ready — paste into <head>. Raises the "structured data" check. -->
+<script type="application/ld+json">
+${jsonldSafe}
+</script>
+<meta property="og:title" content="${escHtml(oneLine(name, 120))}" />
+<meta property="og:description" content="${escHtml(oneLine(description))}" />
+<meta property="og:type" content="website" />
+<meta property="og:url" content="${escHtml(url)}" />
+`
+}
+export function badgeUrl(total) {
+  const color = total >= 80 ? 'brightgreen' : total >= 50 ? 'yellow' : 'red'
+  return `https://img.shields.io/badge/agent--ready-${total}%2F100-${color}`
+}
+export async function writeArtifacts(outDir, a, sc) {
+  await mkdir(outDir, { recursive: true })
+  await Promise.all([
+    writeFile(join(outDir, 'llms.txt'), buildLlmsTxt(a)),
+    writeFile(join(outDir, 'webmcp.tools.js'), buildWebMcp(a)),
+    writeFile(join(outDir, 'structured-data.html'), buildStructuredData(a)),
+    writeFile(
+      join(outDir, 'agent-ready.json'),
+      JSON.stringify(
+        {
+          tool: 'agent-ready',
+          version: '0.4.0',
+          url: a.base,
+          score: sc.total,
+          badge: badgeUrl(sc.total),
+          checks: sc.checks.map((c) => ({ id: c.id, label: c.label, weight: c.weight, pass: c.pass })),
+          counts: { pages: a.pages.length, forms: a.forms.length, actions: a.actions.length, images: a.imgTotal }
+        },
+        null,
+        2
+      ) + '\n'
+    )
+  ])
+}