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/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Veldin Salcinovic
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,142 @@
+# agent-ready
+[![agent-ready: 100/100](https://img.shields.io/badge/agent--ready-100%2F100-brightgreen)](https://agent-ready-web.vercel.app)
+[![npm version](https://img.shields.io/npm/v/agent-readiness?color=cb3837&logo=npm)](https://www.npmjs.com/package/agent-readiness)
+[![CI](https://github.com/VeldinS/agent-ready/actions/workflows/ci.yml/badge.svg)](https://github.com/VeldinS/agent-ready/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+**Make any website agent-ready in one command.** Scan a site, get an agent-readiness score, and auto-generate the two things the agentic web now expects — an `llms.txt` and a **WebMCP** tool scaffold — so AI agents can *understand and act on* your site instead of blindly scraping it.
+```bash
+npx agent-readiness https://yoursite.com
+```
+> **No install?** Scan any site in your browser at **[agent-ready-web.vercel.app](https://agent-ready-web.vercel.app)** — paste a URL, get the score + per-check breakdown, and download the generated `llms.txt` + WebMCP scaffold.
+```
+agent-ready — scanning https://yoursite.com
+  ✗ llms.txt present (0/22)
+     → Add /llms.txt so agents get a clean, token-cheap map of your site (generated below).
+  ✗ WebMCP tools (document.modelContext) (0/22)
+     → Expose your key actions as WebMCP tools so agents can ACT, not just scrape (scaffold generated below).
+  ✔ Structured data (JSON-LD / OpenGraph) (+13/13)
+  ✔ Semantic landmarks + an H1 (+13/13)
+  ✔ Title + meta description (+10/10)
+  ✗ robots.txt + sitemap.xml (0/8)
+  ✔ Canonical URL (<link rel="canonical">) (+4/4)
+  ✔ Document language (<html lang>) (+4/4)
+  ✔ Image alt-text coverage (18/20, 90%) (+4/4)
+  Agent-Readiness: 48/100
+  pages: 17  •  forms: 2  •  inferred actions: 3
+  Generated → ./agent-ready-out/llms.txt, ./agent-ready-out/webmcp.tools.js, ./agent-ready-out/structured-data.html, ./agent-ready-out/agent-ready.json
+```
+## Why this exists
+Chrome's Lighthouse now ships an **"Agentic Browsing"** audit *in the default config* (13.3, May 2026), and **WebMCP** is a W3C draft in origin trial. Millions of sites are about to see a failing agent-readiness grade with no obvious way to fix it. `agent-ready` is the fix: it doesn't just *diagnose* (every scanner does that) — it **generates the artifacts** and is built to run in CI.
+- **`llms.txt`** — a clean, machine-readable map of your pages (with one-line summaries) and actions, built from a multi-page crawl (the emerging standard agents read first).
+- **`webmcp.tools.js`** — a [WebMCP](https://webmachinelearning.github.io/webmcp/) scaffold that registers each `<form>` and inferred action (search / login / signup / cart / checkout / contact / subscribe) as a callable agent tool via `document.modelContext.registerTool(...)`, so an agent can *complete the signup / search / booking* instead of guessing at your DOM.
+- **`structured-data.html`** — a JSON-LD + OpenGraph snippet to drop into your `<head>` so machines get explicit, structured meaning.
+## One command, one PR (the fixer)
+Every other tool *scans*. `agent-ready` also **fixes** — and opens the fix as a pull request:
+```bash
+npx agent-readiness fix ./my-site --pr
+```
+It detects your framework (Next.js App/Pages Router, Vite, or plain static HTML), writes `llms.txt` + `webmcp.tools.js` into the right place, **injects** the `<script>` tag and the missing `<html lang>` / meta description / JSON-LD + OpenGraph into your entry HTML or layout, then branches, commits, and opens a PR with a clear **before → after** score:
+```
+agent-ready fix — ./my-site
+  Framework: Static / plain HTML
+  Score: 17/100 → 88/100
+  Files:
+    + llms.txt          (token-cheap site map for agents)
+    + webmcp.tools.js   (WebMCP tool scaffold)
+    inject → index.html (html-lang, meta-description, structured-data, webmcp-script)
+  ✔ Opened pull request: https://github.com/you/my-site/pull/42
+```
+- `--dry-run` — print the plan (and the exact git/gh commands) without touching anything.
+- `--url https://yoursite.com` — scan the live site for a richer `llms.txt` (multi-page) and to fill real URLs + a canonical tag.
+- `--base <branch>` / `--branch <name>` — control the PR target and head branch.
+- Injection is **idempotent** — re-running never duplicates a tag. `--pr` needs a git repo with an `origin` remote and the [`gh`](https://cli.github.com/) CLI authenticated.
+Prefer to apply locally without a PR? `agent-ready fix ./my-site` writes + injects in place; `agent-ready <url> --apply ./my-site` just drops the files into `public/`.
+## Use it in CI (GitHub Action)
+```yaml
+permissions:
+  contents: read
+  pull-requests: write   # so it can comment the score on the PR
+steps:
+  - uses: VeldinS/agent-ready@v0
+    with:
+      url: https://yoursite.com
+      comment: true        # post a sticky agent-readiness comment on the PR (default)
+      min-score: 60        # optional: fail the job if the score drops below this
+```
+On every pull request it posts (and updates) a single comment with the score and per-check breakdown. Add the badge to your README once you're green:
+```md
+![agent-ready](https://img.shields.io/badge/agent--ready-100%2F100-brightgreen)
+```
+## Use it from your agent (MCP server)
+Run *"make my site agent-ready"* right inside Claude Code / Cursor / Claude Desktop. The [`@veldins/agent-ready-mcp`](mcp/) server exposes two tools — `scan_site` (score + per-check breakdown) and `generate_fixes` (the `llms.txt` + WebMCP scaffold + structured-data contents) — over stdio, sharing the same scanner core.
+```bash
+claude mcp add agent-ready -- npx -y @veldins/agent-ready-mcp
+```
+```json
+{ "mcpServers": { "agent-ready": { "command": "npx", "args": ["-y", "@veldins/agent-ready-mcp"] } } }
+```
+## What it checks
+| Check | Weight |
+|-------|:--:|
+| `llms.txt` present | 22 |
+| WebMCP tools (`document.modelContext`) | 22 |
+| Structured data (JSON-LD / OpenGraph) | 13 |
+| Semantic landmarks + an `<h1>` | 13 |
+| Title + meta description | 10 |
+| `robots.txt` + `sitemap.xml` | 8 |
+| Canonical URL (`<link rel="canonical">`) | 4 |
+| Document language (`<html lang>`) | 4 |
+| Image alt-text coverage (≥80%) | 4 |
+> The score reflects the **server-rendered HTML** an agent first sees; heavily client-rendered SPAs will under-report content checks until they ship meaningful HTML.
+## Roadmap
+- [x] `fix` mode: write + inject the artifacts and open a PR with a before → after score
+- [x] Framework adapters (Next.js App/Pages Router, Vite, static HTML)
+- [x] GitHub Action comments the score on every PR
+- [x] [Web scanner page](https://agent-ready-web.vercel.app): paste a URL → scored report + downloadable fixes (no install)
+- [x] MCP server so Claude Code / Cursor can run "make my site agent-ready" (`@veldins/agent-ready-mcp`)
+- [ ] Re-grade against live Lighthouse Agentic Browsing on each PR
+## Local dev
+```bash
+npm install
+node bin/agent-ready.mjs examples/sample-site.html
+npm test          # node --test — fixtures, generators, crawl, CLI
+```
+One runtime dependency ([`node-html-parser`](https://www.npmjs.com/package/node-html-parser)); Node ≥20.19; ESM; no build step.
+MIT.

package/bin/agent-ready.mjs ADDED Viewed

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs'
+import { writeFile, mkdir } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { crawl, crawlLocal, analyze, score, badgeUrl, writeArtifacts, buildLlmsTxt, buildWebMcp, buildStructuredData } from '../lib/core.mjs'
+import { detectFramework, buildFixPlan, applyFix, gitInfo, ghReady, openPullRequest } from '../lib/fix.mjs'
+import { prBody, commentBody, COMMENT_MARKER } from '../lib/report.mjs'
+import { ghContext, upsertPrComment } from '../lib/github.mjs'
+const C = { g: '\x1b[32m', r: '\x1b[31m', y: '\x1b[33m', d: '\x1b[2m', b: '\x1b[1m', x: '\x1b[0m' }
+const colorFor = (n) => (n >= 80 ? C.g : n >= 50 ? C.y : C.r)
+const USAGE = `usage:
+  agent-ready <url | local.html> [--apply <dir>] [--comment] [--min-score <n>]
+  agent-ready fix <repo-dir> [--url <url>] [--pr] [--dry-run] [--base <branch>] [--branch <name>]`
+// Tiny flag parser. Supports both `--flag value` and `--flag=value`. For a value
+// flag with no value (next token missing or another --flag), the value is null —
+// matching the old --apply guard.
+function parseArgs(args, valueFlags = []) {
+  const flags = {}
+  const positional = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=')
+      const name = eq === -1 ? a.slice(2) : a.slice(2, eq)
+      if (eq !== -1) {
+        flags[name] = a.slice(eq + 1)
+      } else if (valueFlags.includes(name)) {
+        const next = args[i + 1]
+        flags[name] = next === undefined || next.startsWith('--') ? null : args[++i]
+      } else {
+        flags[name] = true
+      }
+    } else {
+      positional.push(a)
+    }
+  }
+  return { flags, positional }
+}
+function stamp() {
+  const d = new Date()
+  const p = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+}
+function printChecks(sc) {
+  for (const c of sc.checks) {
+    const mark = c.pass ? `${C.g}✔${C.x}` : `${C.r}✗${C.x}`
+    console.log(`  ${mark} ${c.label} ${C.d}(${c.pass ? '+' + c.weight : 0}/${c.weight})${C.x}`)
+    if (!c.pass) console.log(`     ${C.d}→ ${c.fix}${C.x}`)
+  }
+}
+// ---------------------------------------------------------------------------
+// scan (default command) — unchanged behavior + --comment / --min-score
+// ---------------------------------------------------------------------------
+async function runScan(args) {
+  const { flags, positional } = parseArgs(args, ['apply', 'min-score'])
+  const arg = positional[0]
+  if (!arg) {
+    console.error(USAGE)
+    process.exit(1)
+  }
+  if ('apply' in flags && !flags.apply) {
+    console.error('--apply requires a <project-dir>, e.g. agent-ready example.com --apply ./my-site')
+    process.exit(1)
+  }
+  const isLocal = existsSync(arg)
+  const target = isLocal ? arg : arg.startsWith('http') ? arg : 'https://' + arg
+  console.log(`\n${C.b}agent-ready${C.x} ${C.d}— scanning ${target}${C.x}\n`)
+  let raw
+  try {
+    raw = isLocal ? await crawlLocal(target) : await crawl(target)
+  } catch (err) {
+    console.error(`${C.r}✗ ${err.message}${C.x}`)
+    process.exit(1)
+  }
+  const a = analyze(raw)
+  const sc = score(a)
+  printChecks(sc)
+  console.log(`\n  ${C.b}Agent-Readiness:${C.x} ${colorFor(sc.total)}${C.b}${sc.total}/100${C.x}`)
+  console.log(`  ${C.d}badge: ${badgeUrl(sc.total)}${C.x}`)
+  console.log(`  ${C.d}pages: ${a.pages.length}  •  forms: ${a.forms.length}  •  inferred actions: ${a.actions.length}${C.x}`)
+  const out = './agent-ready-out'
+  await writeArtifacts(out, a, sc)
+  console.log(`\n  ${C.b}Generated${C.x} → ${out}/llms.txt, ${out}/webmcp.tools.js, ${out}/structured-data.html, ${out}/agent-ready.json`)
+  const applyDir = flags.apply
+  if (applyDir) {
+    const dest = existsSync(join(applyDir, 'public')) ? join(applyDir, 'public') : applyDir
+    await mkdir(dest, { recursive: true })
+    await Promise.all([
+      writeFile(join(dest, 'llms.txt'), buildLlmsTxt(a)),
+      writeFile(join(dest, 'webmcp.tools.js'), buildWebMcp(a)),
+      writeFile(join(dest, 'structured-data.html'), buildStructuredData(a))
+    ])
+    console.log(`\n  ${C.g}${C.b}✔ Applied the fix${C.x} → wrote llms.txt + webmcp.tools.js + structured-data.html into ${C.b}${dest}/${C.x}`)
+    console.log(`  ${C.d}Tip: ${C.x}agent-ready fix <repo-dir>${C.d} injects the <script> tag + meta for you and can open a PR.${C.x}`)
+  } else {
+    console.log(`  ${C.d}Re-run with ${C.x}--apply <project-dir>${C.d}, or ${C.x}agent-ready fix <repo-dir>${C.d} to inject + open a PR.${C.x}`)
+  }
+  if (flags.comment) await maybeComment(target, a, sc)
+  if (flags['min-score'] != null) {
+    const min = Number(flags['min-score'])
+    if (Number.isFinite(min) && sc.total < min) {
+      console.error(`\n${C.r}✗ agent-readiness ${sc.total}/100 is below --min-score ${min}${C.x}`)
+      process.exit(1)
+    }
+  }
+}
+async function maybeComment(target, a, sc) {
+  const ctx = ghContext()
+  if (!ctx) {
+    console.log(`  ${C.d}(--comment: no GitHub PR context/token — skipping)${C.x}`)
+    return
+  }
+  const body = commentBody({
+    url: target,
+    total: sc.total,
+    checks: sc.checks,
+    counts: { pages: a.pages.length, forms: a.forms.length, actions: a.actions.length }
+  })
+  try {
+    const r = await upsertPrComment(ctx, body, COMMENT_MARKER)
+    console.log(`  ${C.g}✔ ${r.updated ? 'Updated' : 'Posted'} the agent-ready PR comment${C.x}`)
+  } catch (err) {
+    console.log(`  ${C.d}(--comment: could not post — ${err.message})${C.x}`)
+  }
+}
+// ---------------------------------------------------------------------------
+// fix (the one-click fixer)
+// ---------------------------------------------------------------------------
+async function runFix(args) {
+  const { flags, positional } = parseArgs(args, ['url', 'base', 'branch'])
+  const repoDir = positional[0]
+  if (!repoDir) {
+    console.error(USAGE)
+    process.exit(1)
+  }
+  if (!existsSync(repoDir)) {
+    console.error(`${C.r}✗ fix: directory not found: ${repoDir}${C.x}`)
+    process.exit(1)
+  }
+  const fw = detectFramework(repoDir)
+  let analysis
+  let baseUrl = null
+  if (flags.url) {
+    const url = flags.url.startsWith('http') ? flags.url : 'https://' + flags.url
+    console.log(`\n${C.b}agent-ready fix${C.x} ${C.d}— scanning ${url} to generate artifacts${C.x}`)
+    try {
+      analysis = analyze(await crawl(url))
+      baseUrl = analysis.base
+    } catch (err) {
+      console.error(`${C.r}✗ fix: could not scan ${url}: ${err.message}${C.x}`)
+      process.exit(1)
+    }
+  } else if (fw.entry && existsSync(fw.entry)) {
+    analysis = analyze({ base: '', home: readFileSync(fw.entry, 'utf8') })
+  } else {
+    analysis = analyze({ base: '', home: '' })
+  }
+  const plan = buildFixPlan({ framework: fw, analysis, baseUrl })
+  console.log(`\n${C.b}agent-ready fix${C.x} ${C.d}— ${fw.root}${C.x}\n`)
+  console.log(`  ${C.b}Framework:${C.x} ${fw.label}`)
+  console.log(`  ${C.d}files dir: ${plan.framework.publicDir}${C.x}`)
+  console.log(`  ${C.d}entry:     ${fw.entry || '(none detected)'}${C.x}`)
+  console.log(
+    `\n  ${C.b}Score:${C.x} ${plan.before.total}/100 → ${colorFor(plan.after.total)}${C.b}${plan.after.total}/100${C.x}${plan.after.projected ? C.d + ' (projected after deploy)' + C.x : ''}\n`
+  )
+  console.log(`  ${C.b}Files:${C.x}`)
+  for (const w of plan.writes) console.log(`    ${w.exists ? '~' : C.g + '+' + C.x} ${w.rel} ${C.d}(${w.label})${C.x}`)
+  if (plan.injection) console.log(`    ${C.d}inject → ${plan.injection.entryRel} (${plan.injection.applied.join(', ') || 'no changes needed'})${C.x}`)
+  if (plan.notes.length) {
+    console.log(`\n  ${C.b}Notes:${C.x}`)
+    for (const n of plan.notes) console.log(`    ${C.d}• ${n}${C.x}`)
+  }
+  if (flags['dry-run']) {
+    console.log(`\n  ${C.y}dry run — no files written.${C.x}`)
+    if (flags.pr) {
+      const gi = gitInfo(repoDir)
+      const base = resolveBase(gi, flags) || 'main'
+      const branch = flags.branch || `agent-ready/fix-${stamp()}`
+      const filesRel = changedRel(gi, plan)
+      const pr = openPullRequest({ root: gi && gi.root, branch, base, files: filesRel, title: prTitle(plan), body: '', dryRun: true })
+      console.log(`\n  ${C.b}Would open a PR with:${C.x}`)
+      for (const cmd of pr.commands) console.log(`    ${C.d}$ ${cmd}${C.x}`)
+    }
+    return
+  }
+  let gi = null
+  let base = null
+  if (flags.pr) {
+    gi = gitInfo(repoDir)
+    if (!gi) {
+      console.error(`\n${C.r}✗ fix --pr: not a git repository. Run \`git init\` and add a GitHub remote first.${C.x}`)
+      process.exit(1)
+    }
+    if (!gi.hasOrigin) {
+      console.error(`\n${C.r}✗ fix --pr: no \`origin\` remote — push this repo to GitHub first.${C.x}`)
+      process.exit(1)
+    }
+    if (!ghReady(gi.root)) {
+      console.error(`\n${C.r}✗ fix --pr: GitHub CLI (gh) is not installed or not authenticated. Install gh and run \`gh auth login\`.${C.x}`)
+      process.exit(1)
+    }
+    base = resolveBase(gi, flags)
+    if (!base) {
+      console.error(`\n${C.r}✗ fix --pr: detached HEAD and no default branch found — pass --base <branch>.${C.x}`)
+      process.exit(1)
+    }
+  }
+  const changed = await applyFix(plan)
+  console.log(`\n  ${C.g}${C.b}✔ Applied${C.x} — wrote/updated ${changed.length} file(s).`)
+  if (flags.pr) {
+    const branch = flags.branch || `agent-ready/fix-${stamp()}`
+    const filesRel = changed.map((abs) => relative(gi.root, abs))
+    const title = prTitle(plan)
+    const body = prBody({ before: plan.before, after: plan.after, framework: fw, writes: plan.writes, injection: plan.injection, notes: plan.notes })
+    try {
+      const r = openPullRequest({ root: gi.root, branch, base, files: filesRel, title, body, dryRun: false })
+      if (r.noChanges) {
+        console.log(`\n  ${C.g}${C.b}✔ Already agent-ready${C.x} — the artifacts match what's committed; no PR needed.`)
+      } else {
+        console.log(`\n  ${C.g}${C.b}✔ Opened pull request:${C.x} ${r.url}`)
+      }
+    } catch (err) {
+      console.error(`\n${C.r}✗ Could not open the PR: ${err.message}${C.x}`)
+      console.error(`${C.d}  ${recoveryHint(err)}${C.x}`)
+      process.exit(1)
+    }
+  } else {
+    console.log(`  ${C.d}Re-run with ${C.x}--pr${C.d} to branch, commit, and open a pull request.${C.x}`)
+  }
+}
+// PR base = explicit --base, else the repo's default branch, else the current
+// branch (unless detached). null means "couldn't determine — ask the user".
+function resolveBase(gi, flags) {
+  if (flags.base) return flags.base
+  if (!gi) return null
+  if (gi.defaultBranch) return gi.defaultBranch
+  return gi.detached ? null : gi.branch
+}
+// Describe the repo's true state for the stage the PR flow failed at.
+function recoveryHint(err) {
+  switch (err.agentReadyStage) {
+    case 'pushed':
+      return `branch "${err.branch}" was committed and pushed to origin — open the PR from GitHub, or delete the branch and retry.`
+    case 'committed':
+      return `changes were committed locally on "${err.branch}" but not pushed.`
+    default:
+      return 'the fix files were written to your working tree; commit + open the PR manually.'
+  }
+}
+function prTitle(plan) {
+  return `agent-ready: add llms.txt + WebMCP scaffold (score ${plan.before.total}→${plan.after.total})`
+}
+function changedRel(gi, plan) {
+  const abs = [...plan.writes.map((w) => w.abs)]
+  if (plan.injection && plan.injection.after !== plan.injection.before) abs.push(plan.injection.entryAbs)
+  return gi ? abs.map((p) => relative(gi.root, p)) : abs
+}
+// ---------------------------------------------------------------------------
+const argv = process.argv.slice(2)
+if (argv[0] === 'fix') {
+  await runFix(argv.slice(1))
+} else {
+  await runScan(argv)
+}