agent-readiness 0.4.0

package/lib/fix.mjs

@@ -0,0 +1,564 @@
+// The fixer: turn a scanned analysis into concrete file writes + entry-file edits
+// for a real project, place them in the right spot per framework, and (optionally)
+// open a pull request. Kept separate from core.mjs so core stays framework-agnostic.
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { writeFile, mkdir } from 'node:fs/promises'
+import { execFileSync } from 'node:child_process'
+import { join, dirname, resolve, relative } from 'node:path'
+import { tmpdir } from 'node:os'
+import { score, buildLlmsTxt, buildWebMcp, buildStructuredData } from './core.mjs'
+
+const SCRIPT_SRC = '/webmcp.tools.js'
+const MCP_SCRIPT = `<script src="${SCRIPT_SRC}" defer></script>`
+
+// ---------------------------------------------------------------------------
+// Framework detection
+// ---------------------------------------------------------------------------
+
+const LAYOUT_EXT = ['tsx', 'jsx', 'ts', 'js', 'mjs']
+
+function readJson(p) {
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function firstExisting(paths) {
+  for (const p of paths) if (p && existsSync(p)) return p
+  return null
+}
+
+function layoutCandidates(root, dirs, base) {
+  return dirs.flatMap((d) => LAYOUT_EXT.map((e) => join(root, d, `${base}.${e}`)))
+}
+
+function mk(id, label, root, publicDir, entry, entryKind) {
+  return { id, label, root, publicDir, entry, entryKind }
+}
+
+// Returns { id, label, root, publicDir, entry, entryKind }.
+//   entryKind: 'html' (a real HTML doc we can fully inject) | 'jsx' (a React/Next
+//   layout we edit conservatively) | null (nothing to inject into).
+export function detectFramework(repoDir) {
+  const root = resolve(repoDir)
+  const pkg = readJson(join(root, 'package.json')) || {}
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) }
+  const dep = (n) => Boolean(deps[n])
+  const cfg = (names) => firstExisting(names.map((n) => join(root, n)))
+
+  if (dep('next') || cfg(['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs'])) {
+    const appLayout = firstExisting(layoutCandidates(root, ['app', 'src/app'], 'layout'))
+    if (appLayout) return mk('next-app', 'Next.js (App Router)', root, join(root, 'public'), appLayout, 'jsx')
+    const entry = firstExisting(layoutCandidates(root, ['pages', 'src/pages'], '_document')) || firstExisting(layoutCandidates(root, ['pages', 'src/pages'], '_app'))
+    return mk('next-pages', 'Next.js (Pages Router)', root, join(root, 'public'), entry, entry ? 'jsx' : null)
+  }
+
+  if (dep('vite') || cfg(['vite.config.js', 'vite.config.ts', 'vite.config.mjs'])) {
+    const html = firstExisting([join(root, 'index.html')])
+    return mk('vite', 'Vite', root, join(root, 'public'), html, html ? 'html' : null)
+  }
+
+  const html = firstExisting([join(root, 'index.html'), join(root, 'public', 'index.html'), join(root, 'src', 'index.html'), join(root, 'dist', 'index.html')])
+  if (html) {
+    const publicDir = existsSync(join(root, 'public')) ? join(root, 'public') : dirname(html)
+    return mk('static', 'Static / plain HTML', root, publicDir, html, 'html')
+  }
+
+  return mk('unknown', 'Unknown project', root, existsSync(join(root, 'public')) ? join(root, 'public') : root, null, null)
+}
+
+// ---------------------------------------------------------------------------
+// Injection (idempotent — re-running never duplicates)
+// ---------------------------------------------------------------------------
+
+function escHtml(s) {
+  return String(s == null ? '' : s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+// Blank out spans that must NOT host an injection anchor — HTML comments,
+// script/style/pre/textarea bodies (for 'html'); JS comments + string/template
+// literals (for 'jsx'). Same length, newlines preserved, so an index found in
+// the mask maps 1:1 back into the original string. This stops us from splicing a
+// tag inside a comment or a string (which would silently corrupt the file).
+function maskNonInjectable(s, kind) {
+  const patterns =
+    kind === 'jsx'
+      ? [/\/\*[\s\S]*?\*\//g, /\/\/[^\n]*/g, /"(?:[^"\\]|\\.)*"/g, /'(?:[^'\\]|\\.)*'/g, /`(?:[^`\\]|\\.)*`/g]
+      : [/<!--[\s\S]*?-->/g, /<script\b[\s\S]*?<\/script\s*>/gi, /<style\b[\s\S]*?<\/style\s*>/gi, /<pre\b[\s\S]*?<\/pre\s*>/gi, /<textarea\b[\s\S]*?<\/textarea\s*>/gi]
+  const arr = s.split('')
+  for (const re of patterns) {
+    for (const m of s.matchAll(re)) {
+      for (let i = m.index; i < m.index + m[0].length && i < arr.length; i++) {
+        if (arr[i] !== '\n') arr[i] = ' '
+      }
+    }
+  }
+  return arr.join('')
+}
+
+// Insert `lines` just before the first real closing </tag> (located via `mask`),
+// matching its indentation and preserving its original casing/spacing.
+function insertBeforeClose(str, mask, tag, lines) {
+  const m = mask.match(new RegExp(`([ \\t]*)</${tag}\\s*>`, 'i'))
+  if (!m) return null
+  const indent = m[1] || ''
+  const tagStart = m.index + indent.length
+  const tagEnd = m.index + m[0].length
+  const closeText = str.slice(tagStart, tagEnd) // author's exact closing tag
+  const block = lines.map((l) => `${indent}  ${l}`).join('\n')
+  return str.slice(0, m.index) + block + '\n' + indent + closeText + str.slice(tagEnd)
+}
+
+// Insert `lines` immediately after the first real opening <tag ...> (via `mask`).
+function insertAfterOpen(str, mask, tag, lines) {
+  const m = mask.match(new RegExp(`<${tag}(?:\\s[^>]*)?>`, 'i'))
+  if (!m) return null
+  const at = m.index + m[0].length
+  const block = '\n' + lines.map((l) => `  ${l}`).join('\n')
+  return str.slice(0, at) + block + str.slice(at)
+}
+
+// Add lang="…" to the first real <html|Html> open tag, preserving its casing
+// (so next/document's <Html> isn't lowercased into a tag-mismatch build error).
+function addHtmlLang(out, mask, lang) {
+  if (!lang) return null
+  const m = mask.match(/<html(?=[\s>{])/i)
+  if (!m) return null
+  const gt = out.indexOf('>', m.index)
+  const openTag = out.slice(m.index, gt === -1 ? out.length : gt)
+  if (/\slang\s*=/i.test(openTag)) return null
+  return out.slice(0, m.index) + out.slice(m.index).replace(/<html(?=[\s>{])/i, (mm) => `${mm} lang="${escHtml(lang)}"`)
+}
+
+// Inject into a real HTML document: lang, title, meta description, canonical,
+// structured-data block, and the WebMCP <script>. Each guarded so it only adds
+// what's missing; anything it can't place safely is reported via `manual`.
+export function injectHtml(src, gaps) {
+  let out = src
+  const applied = []
+  const manual = []
+  let mask = maskNonInjectable(out, 'html')
+
+  const langed = addHtmlLang(out, mask, gaps.lang)
+  if (langed) {
+    out = langed
+    applied.push('html-lang')
+    mask = maskNonInjectable(out, 'html')
+  }
+
+  // Presence checks run against the ORIGINAL source (not the mask) — otherwise a
+  // real <script type="application/ld+json"> would read as absent (it's masked)
+  // and get duplicated on re-runs. The mask is only for locating injection anchors.
+  const head = []
+  const headLabels = []
+  if (gaps.title && !/<title[\s>]/i.test(out)) {
+    head.push(`<title>${escHtml(gaps.title)}</title>`)
+    headLabels.push('title')
+  }
+  if (gaps.description && !/<meta[^>]+name=["']?description/i.test(out)) {
+    head.push(`<meta name="description" content="${escHtml(gaps.description)}" />`)
+    headLabels.push('meta-description')
+  }
+  if (gaps.canonical && !/<link[^>]+rel=["']?canonical/i.test(out)) {
+    head.push(`<link rel="canonical" href="${escHtml(gaps.canonical)}" />`)
+    headLabels.push('canonical')
+  }
+  if (gaps.structured && !/application\/ld\+json/i.test(out)) {
+    head.push(...String(gaps.structured).trim().split('\n'))
+    headLabels.push('structured-data')
+  }
+  if (head.length) {
+    const placed = insertBeforeClose(out, mask, 'head', head) || insertAfterOpen(out, mask, 'head', head) || insertAfterOpen(out, mask, 'html', head)
+    if (placed) {
+      out = placed
+      applied.push(...headLabels)
+      mask = maskNonInjectable(out, 'html')
+    } else {
+      manual.push(`Could not find a <head>/<html> tag — add to your <head> manually: ${headLabels.join(', ')}.`)
+    }
+  }
+
+  if (gaps.webmcp && !out.includes(SCRIPT_SRC)) {
+    const placed = insertBeforeClose(out, mask, 'body', [MCP_SCRIPT]) || insertBeforeClose(out, mask, 'head', [MCP_SCRIPT])
+    if (placed) {
+      out = placed
+      applied.push('webmcp-script')
+    } else {
+      manual.push(`Could not find </body> or </head> — add \`${MCP_SCRIPT}\` to your page manually.`)
+    }
+  }
+
+  return { html: out, applied, manual }
+}
+
+// Inject into a React/Next layout: only the two edits that are safe in JSX —
+// the <html lang> attribute and a <script> before </body>. Metadata/structured
+// data is left to a note (App Router uses the `metadata` export, not raw tags).
+export function injectLayout(src, gaps) {
+  let out = src
+  const applied = []
+  const manual = []
+  let mask = maskNonInjectable(out, 'jsx')
+
+  const langed = addHtmlLang(out, mask, gaps.lang)
+  if (langed) {
+    out = langed
+    applied.push('html-lang')
+    mask = maskNonInjectable(out, 'jsx')
+  }
+
+  if (gaps.webmcp && !out.includes(SCRIPT_SRC)) {
+    const placed = insertBeforeClose(out, mask, 'body', [MCP_SCRIPT])
+    if (placed) {
+      out = placed
+      applied.push('webmcp-script')
+    } else {
+      manual.push(`Add \`${MCP_SCRIPT}\` to your layout (no \`</body>\` found to inject before).`)
+    }
+  }
+
+  return { html: out, applied, manual }
+}
+
+// ---------------------------------------------------------------------------
+// Gap analysis + planning
+// ---------------------------------------------------------------------------
+
+// Which gap keys a framework can apply automatically. HTML docs get the full set;
+// JSX layouts only get the two safe edits; an unknown project gets none (file
+// writes still happen, but presence checks that need an entry edit won't flip).
+function autoApplicable(framework) {
+  if (framework.entryKind === 'html') return new Set(['lang', 'title', 'description', 'structured', 'webmcp', 'canonical'])
+  if (framework.entryKind === 'jsx') return new Set(['lang', 'webmcp'])
+  return new Set()
+}
+
+function titleFrom(baseUrl) {
+  try {
+    if (baseUrl) return new URL(baseUrl).hostname
+  } catch {
+    /* ignore */
+  }
+  return 'Site'
+}
+
+function computeGaps(facts, baseUrl) {
+  return {
+    lang: facts.htmlLang ? null : 'en',
+    title: facts.title ? null : titleFrom(baseUrl),
+    // Seed the description from the page <title> when present — a sensible starting
+    // point the dev should refine (flagged in notes), better than a bare placeholder.
+    description: facts.description ? null : facts.title || 'A short description of what this site is and does.',
+    structured: facts.hasJsonLd || facts.hasOg ? null : true,
+    webmcp: facts.hasWebMcp ? null : true,
+    canonical: facts.hasCanonical ? null : baseUrl || null
+  }
+}
+
+function hasContentFile(paths) {
+  for (const p of paths) {
+    try {
+      const s = readFileSync(p, 'utf8')
+      if (s && s.trim().length > 20) return true
+    } catch {
+      /* ignore */
+    }
+  }
+  return false
+}
+
+// Filesystem presence (for local mode, where the crawl can't tell us).
+function repoPresence(framework) {
+  const pub = (n) => join(framework.publicDir, n)
+  const root = (n) => join(framework.root, n)
+  return {
+    hasLlmsTxt: hasContentFile([pub('llms.txt'), root('llms.txt')]),
+    hasRobots: existsSync(pub('robots.txt')) || existsSync(root('robots.txt')),
+    hasSitemap: existsSync(pub('sitemap.xml')) || existsSync(root('sitemap.xml'))
+  }
+}
+
+function writeSpec(framework, name, content, label) {
+  const abs = join(framework.publicDir, name)
+  return { abs, rel: relative(framework.root, abs) || name, content, label, exists: existsSync(abs) }
+}
+
+// Build the full fix plan: file writes, the entry-file injection, projected
+// before/after scores, and honest notes about what still needs a human.
+// `baseUrl` (truthy when scanned via --url) switches "after" to a projection
+// and unlocks the canonical injection.
+export function buildFixPlan({ framework, analysis, baseUrl = null }) {
+  const fromUrl = Boolean(baseUrl)
+
+  const beforeFacts = { ...analysis }
+  if (!fromUrl) {
+    const pres = repoPresence(framework)
+    beforeFacts.hasLlmsTxt = pres.hasLlmsTxt
+    beforeFacts.hasRobots = pres.hasRobots
+    beforeFacts.hasSitemap = pres.hasSitemap
+  }
+  const before = score(beforeFacts)
+
+  const gaps = computeGaps(beforeFacts, baseUrl)
+  const auto = autoApplicable(framework)
+  const eligible = {}
+  for (const k of ['lang', 'title', 'description', 'structured', 'webmcp', 'canonical']) eligible[k] = auto.has(k) && Boolean(gaps[k])
+
+  // Seed the structured-data snippet with the same description we inject as <meta>,
+  // and the live origin when we have one, so the JSON-LD isn't full of placeholders.
+  const structuredHtml = buildStructuredData({
+    ...analysis,
+    base: analysis.base || baseUrl || '',
+    description: analysis.description || (typeof gaps.description === 'string' ? gaps.description : '')
+  })
+  const writes = [
+    writeSpec(framework, 'llms.txt', buildLlmsTxt(analysis), 'token-cheap site map for agents'),
+    writeSpec(framework, 'webmcp.tools.js', buildWebMcp(analysis), 'WebMCP tool scaffold (document.modelContext.registerTool)')
+  ]
+
+  const notes = []
+  const injectStructured = eligible.structured && framework.entryKind === 'html'
+  // When we can't inject structured data into the entry (JSX/no-entry), ship it as
+  // a snippet file the dev pastes in — with router-accurate guidance.
+  if (gaps.structured && !injectStructured) {
+    writes.push(writeSpec(framework, 'structured-data.html', structuredHtml, 'JSON-LD + OpenGraph snippet for your <head>'))
+    if (framework.id === 'next-app') {
+      notes.push('Add the OpenGraph fields via your `metadata` export and render the JSON-LD as a `<script type="application/ld+json">` in the App Router layout.')
+    } else if (framework.id === 'next-pages') {
+      notes.push('Add the JSON-LD + OpenGraph from `structured-data.html` via `<Head>` from `next/document` in `_document` (or `next/head` per page).')
+    } else {
+      notes.push('Add the JSON-LD + OpenGraph from `structured-data.html` to your `<head>`.')
+    }
+  }
+
+  let injection = null
+  if (framework.entry && framework.entryKind) {
+    const src = readFileSync(framework.entry, 'utf8')
+    const injGaps = {
+      lang: eligible.lang ? gaps.lang : null,
+      title: eligible.title ? gaps.title : null,
+      description: eligible.description ? gaps.description : null,
+      canonical: eligible.canonical ? gaps.canonical : null,
+      structured: injectStructured ? structuredHtml : null,
+      webmcp: eligible.webmcp ? true : null
+    }
+    const res = framework.entryKind === 'html' ? injectHtml(src, injGaps) : injectLayout(src, injGaps)
+    injection = {
+      entryAbs: framework.entry,
+      entryRel: relative(framework.root, framework.entry),
+      kind: framework.entryKind,
+      before: src,
+      after: res.html,
+      applied: res.applied
+    }
+    if (res.manual && res.manual.length) notes.push(...res.manual)
+    if (injection.applied.includes('meta-description')) notes.push('Review the injected `<meta name="description">` — it was seeded from your `<title>`.')
+  } else if (gaps.webmcp) {
+    notes.push(`No entry HTML/layout detected — add \`${MCP_SCRIPT}\` to your site's \`<head>\`/\`<body>\` so the WebMCP tools load.`)
+  }
+
+  // Project the "after" score from what injection ACTUALLY applied (not from what
+  // was merely eligible) — a no-op/failed splice must never inflate the score.
+  // llms.txt is unconditional because applyFix always writes the file.
+  const afterFacts = { ...beforeFacts, hasLlmsTxt: true }
+  const did = new Set(injection ? injection.applied : [])
+  if (did.has('webmcp-script')) afterFacts.hasWebMcp = true
+  if (did.has('html-lang')) afterFacts.htmlLang = gaps.lang
+  if (did.has('meta-description')) afterFacts.description = gaps.description
+  if (did.has('title')) afterFacts.title = gaps.title
+  if (did.has('canonical')) afterFacts.hasCanonical = true
+  if (did.has('structured-data')) {
+    afterFacts.hasJsonLd = true
+    afterFacts.hasOg = true
+  }
+  const after = score(afterFacts)
+  after.projected = fromUrl
+
+  if (!afterFacts.hasRobots || !afterFacts.hasSitemap) notes.push('`fix` does not generate robots.txt + sitemap.xml yet — add them for the discovery check (+8).')
+  if (!baseUrl && (injectStructured || gaps.canonical) && framework.entryKind === 'html') {
+    notes.push('Re-run with `--url https://yoursite.com` to fill real URLs in the structured data and inject `<link rel="canonical">` (+4).')
+  }
+
+  return { framework, before, after, gaps, eligible, writes, injection, notes }
+}
+
+// Perform the plan's writes + entry edit. Returns the absolute paths it changed.
+export async function applyFix(plan) {
+  const changed = []
+  await mkdir(plan.framework.publicDir, { recursive: true })
+  for (const w of plan.writes) {
+    await writeFile(w.abs, w.content)
+    changed.push(w.abs)
+  }
+  if (plan.injection && plan.injection.after !== plan.injection.before) {
+    await writeFile(plan.injection.entryAbs, plan.injection.after)
+    changed.push(plan.injection.entryAbs)
+  }
+  return changed
+}
+
+// ---------------------------------------------------------------------------
+// Git / GitHub PR
+// ---------------------------------------------------------------------------
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+}
+
+// Returns { root, branch, detached, hasOrigin, defaultBranch } for the git repo
+// containing `cwd`, or null. defaultBranch is resolved from origin/HEAD, then a
+// local main/master — so a PR targets the real default, not whatever branch the
+// user happens to be on.
+export function gitInfo(cwd) {
+  try {
+    const root = git(['rev-parse', '--show-toplevel'], cwd)
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], root)
+    const detached = branch === 'HEAD'
+    let hasOrigin = true
+    try {
+      git(['remote', 'get-url', 'origin'], root)
+    } catch {
+      hasOrigin = false
+    }
+    let defaultBranch = null
+    if (hasOrigin) {
+      try {
+        defaultBranch = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], root).replace(/^origin\//, '')
+      } catch {
+        /* origin/HEAD not set locally */
+      }
+    }
+    if (!defaultBranch) {
+      for (const cand of ['main', 'master']) {
+        try {
+          git(['rev-parse', '--verify', '--quiet', `refs/heads/${cand}`], root)
+          defaultBranch = cand
+          break
+        } catch {
+          /* not present */
+        }
+      }
+    }
+    return { root, branch, detached, hasOrigin, defaultBranch }
+  } catch {
+    return null
+  }
+}
+
+// gh installed AND authenticated? (`gh auth status` exits non-zero for both a
+// missing binary — ENOENT — and an unauthenticated CLI, so one check covers both.)
+export function ghReady(cwd) {
+  try {
+    execFileSync('gh', ['auth', 'status'], { cwd, stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function branchExists(root, branch) {
+  try {
+    git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], root)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function nothingStaged(root) {
+  // `git diff --cached --quiet` exits 0 when nothing is staged, non-zero otherwise.
+  try {
+    execFileSync('git', ['diff', '--cached', '--quiet'], { cwd: root, stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function stageError(message, stage, branch) {
+  const e = new Error(message)
+  e.agentReadyStage = stage
+  e.branch = branch
+  return e
+}
+
+// Branch, commit the given (repo-root-relative) files, push, and open a PR via gh.
+// With dryRun, returns the exact command list instead of executing anything.
+// Returns { url } on success, { noChanges: true } when the tree already matches.
+// On failure, throws with err.agentReadyStage ∈ {preflight, start, committed, pushed}
+// so the caller can describe the repo's true state. Always returns the user to the
+// branch they started on; cleans up the temp body file.
+export function openPullRequest({ root, branch, base, files, title, body, dryRun = false }) {
+  const bodyFile = join(tmpdir(), `agent-ready-pr-${Date.now()}.md`)
+  const commands = [
+    `git checkout -b ${branch}`,
+    `git add ${files.join(' ')}`,
+    `git commit -m "${title}"`,
+    `git push -u origin ${branch}`,
+    `gh pr create --base ${base} --head ${branch} --title "${title}" --body-file ${bodyFile}`
+  ]
+  if (dryRun) return { dryRun: true, branch, base, bodyFile, commands }
+
+  if (branchExists(root, branch)) {
+    throw stageError(`branch "${branch}" already exists — pass a different --branch <name> or delete it (git branch -D ${branch}).`, 'preflight', branch)
+  }
+
+  let startRef = null
+  try {
+    startRef = git(['rev-parse', '--abbrev-ref', 'HEAD'], root)
+  } catch {
+    /* leave null */
+  }
+  writeFileSync(bodyFile, body, { mode: 0o600 })
+
+  let stage = 'start'
+  let onBranch = false
+  try {
+    git(['checkout', '-b', branch], root)
+    onBranch = true
+    git(['add', ...files], root)
+    if (nothingStaged(root)) {
+      // Identical re-run / already agent-ready — undo the empty branch and bail cleanly.
+      if (startRef && startRef !== 'HEAD') {
+        try {
+          git(['checkout', startRef], root)
+          git(['branch', '-D', branch], root)
+          onBranch = false
+        } catch {
+          /* if we can't return, leave the branch rather than throw */
+        }
+      }
+      return { noChanges: true, branch }
+    }
+    git(['commit', '-m', title], root)
+    stage = 'committed'
+    git(['push', '-u', 'origin', branch], root)
+    stage = 'pushed'
+    const url = execFileSync('gh', ['pr', 'create', '--base', base, '--head', branch, '--title', title, '--body-file', bodyFile], { cwd: root, encoding: 'utf8' }).trim()
+    return { url, branch, base }
+  } catch (err) {
+    if (!err.agentReadyStage) err.agentReadyStage = stage
+    err.branch = branch
+    throw err
+  } finally {
+    try {
+      unlinkSync(bodyFile)
+    } catch {
+      /* ignore */
+    }
+    // Return to the branch the user started on (the fix branch stays for the PR).
+    if (onBranch && startRef && startRef !== 'HEAD') {
+      try {
+        if (git(['rev-parse', '--abbrev-ref', 'HEAD'], root) === branch) git(['checkout', startRef], root)
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}

package/lib/github.mjs

@@ -0,0 +1,51 @@
+// Minimal GitHub REST client (fetch-based, no deps) for the Action's PR-comment
+// mode. Reads the standard env GitHub Actions sets for every step.
+import { readFileSync } from 'node:fs'
+
+// Returns { token, repo, apiUrl, prNumber } when running inside a PR job with a
+// token, else null (so callers can no-op cleanly outside that context).
+export function ghContext(env = process.env) {
+  const token = env.GITHUB_TOKEN || env.GH_TOKEN
+  const repo = env.GITHUB_REPOSITORY // "owner/name"
+  const apiUrl = env.GITHUB_API_URL || 'https://api.github.com'
+  let prNumber = null
+  if (env.GITHUB_EVENT_PATH) {
+    try {
+      const ev = JSON.parse(readFileSync(env.GITHUB_EVENT_PATH, 'utf8'))
+      prNumber = ev?.pull_request?.number ?? ev?.issue?.number ?? null
+    } catch {
+      /* not a PR event payload */
+    }
+  }
+  if (!token || !repo || !prNumber) return null
+  return { token, repo, apiUrl, prNumber }
+}
+
+async function api(ctx, path, opts = {}) {
+  const res = await fetch(`${ctx.apiUrl}${path}`, {
+    ...opts,
+    headers: {
+      authorization: `Bearer ${ctx.token}`,
+      accept: 'application/vnd.github+json',
+      'user-agent': 'agent-ready',
+      'x-github-api-version': '2022-11-28',
+      ...(opts.body ? { 'content-type': 'application/json' } : {}),
+      ...(opts.headers || {})
+    }
+  })
+  if (!res.ok) throw new Error(`GitHub API ${res.status} ${res.statusText} (${path})`)
+  return res.status === 204 ? null : res.json()
+}
+
+// Create — or update, if one already exists — a single comment identified by a
+// hidden marker, so re-runs refresh one comment instead of spamming the PR.
+export async function upsertPrComment(ctx, body, marker) {
+  const existing = await api(ctx, `/repos/${ctx.repo}/issues/${ctx.prNumber}/comments?per_page=100`).catch(() => [])
+  const mine = Array.isArray(existing) ? existing.find((c) => typeof c.body === 'string' && c.body.includes(marker)) : null
+  if (mine) {
+    await api(ctx, `/repos/${ctx.repo}/issues/comments/${mine.id}`, { method: 'PATCH', body: JSON.stringify({ body }) })
+    return { updated: true, id: mine.id }
+  }
+  const created = await api(ctx, `/repos/${ctx.repo}/issues/${ctx.prNumber}/comments`, { method: 'POST', body: JSON.stringify({ body }) })
+  return { updated: false, id: created?.id }
+}

package/lib/report.mjs

@@ -0,0 +1,57 @@
+// Markdown report builders shared by the PR body (`fix --pr`) and the PR comment
+// (GitHub Action `--comment` mode). Kept dependency-free.
+import { badgeUrl } from './core.mjs'
+
+export const COMMENT_MARKER = '<!-- agent-ready-report -->'
+
+function cell(s) {
+  return String(s).replace(/\|/g, '\\|')
+}
+
+export function checksTable(checks) {
+  const rows = checks.map((c) => `| ${c.pass ? '✅' : '❌'} | ${cell(c.label)} | ${c.pass ? '+' + c.weight : 0} / ${c.weight} |`)
+  return ['| | Check | Points |', '|:--:|---|---:|', ...rows].join('\n')
+}
+
+export function scoreHeadline(total) {
+  return `**Agent-Readiness: ${total}/100** &nbsp; ![score](${badgeUrl(total)})`
+}
+
+// The body for the pull request opened by `agent-ready fix --pr`.
+export function prBody({ before, after, framework, writes, injection, notes }) {
+  const projected = Boolean(after.projected)
+  const L = []
+  L.push('## 🤖 agent-ready — make this site agent-ready', '')
+  L.push(
+    'Generated by [agent-ready](https://github.com/VeldinS/agent-ready). It adds the artifacts the agentic web now expects — an [`llms.txt`](https://llmstxt.org/) and a [WebMCP](https://webmachinelearning.github.io/webmcp/) tool scaffold — plus the missing metadata, so AI agents can *understand and act on* this site instead of blindly scraping it.',
+    ''
+  )
+  L.push(`**Detected framework:** ${framework.label}`, '')
+  L.push('### Score', '')
+  L.push(`| | Before | After${projected ? ' (projected)' : ''} |`, '|---|:--:|:--:|', `| Agent-Readiness | **${before.total}/100** | **${after.total}/100** |`, '')
+  L.push('<details><summary>Per-check breakdown (after)</summary>', '', checksTable(after.checks), '</details>', '')
+  L.push('### What changed', '')
+  for (const w of writes) L.push(`- \`${w.rel}\`${w.exists ? ' (updated)' : ''} — ${w.label}`)
+  if (injection && injection.applied.length) L.push(`- \`${injection.entryRel}\` — injected: ${injection.applied.join(', ')}`)
+  L.push('')
+  if (notes && notes.length) {
+    L.push('### Notes / remaining manual steps', '')
+    for (const n of notes) L.push(`- ${n}`)
+    L.push('')
+  }
+  if (projected) L.push('> "After (projected)" is the score once this is deployed; re-scan the live URL to confirm.', '')
+  L.push('---', '<sub>🤖 Opened by <a href="https://github.com/VeldinS/agent-ready">agent-ready</a> — review before merging.</sub>')
+  return L.join('\n')
+}
+
+// The sticky comment posted on a PR by the GitHub Action.
+export function commentBody({ url, total, checks, counts }) {
+  const L = []
+  L.push(COMMENT_MARKER)
+  L.push(`## 🤖 agent-ready — \`${url}\``, '')
+  L.push(scoreHeadline(total), '')
+  L.push(checksTable(checks), '')
+  if (counts) L.push(`<sub>pages: ${counts.pages} • forms: ${counts.forms} • inferred actions: ${counts.actions}</sub>`, '')
+  L.push('<sub>Generate the fixes locally: <code>npx agent-readiness fix .</code> · <a href="https://github.com/VeldinS/agent-ready">agent-ready</a></sub>')
+  return L.join('\n')
+}