avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/external-readiness/endpoint-prober.js

@@ -0,0 +1,332 @@
+'use strict';
+
+const https = require('https');
+const http = require('http');
+
+const DEFAULTS = {
+  perProbeTimeoutMs: 2500,
+  siteBudgetMs: 35000,
+  maxConcurrencyPerHost: 4,
+  maxConcurrencyPerSite: 8,
+  maxRedirects: 3,
+  maxSnippetBytes: 16384,
+};
+
+// Probe definitions in priority order
+const MACHINE_READABLE = [
+  { key: 'openapi', path: '/openapi.json' },
+  { key: 'openapi', path: '/openapi.yaml' },
+  { key: 'swagger', path: '/swagger.json' },
+  { key: 'llmsTxt', path: '/llms.txt' },
+  { key: 'llmsTxtFull', path: '/llms-full.txt' },
+];
+const HIGH_SIGNAL_DOCS = [
+  { key: 'docs', path: '/docs' },
+  { key: 'developerDocs', path: '/developers' },
+  { key: 'developerDocs', path: '/developer' },
+  { key: 'apiDocs', path: '/api' },
+  { key: 'apiDocs', path: '/api-reference' },
+  { key: 'apiDocs', path: '/api/docs' },
+];
+const AUTH_PROBES = [
+  { key: 'oauthDiscovery', path: '/.well-known/oauth-authorization-server' },
+  { key: 'oauth', path: '/oauth' },
+  { key: 'authMd', path: '/auth.md' },
+];
+const LOWER_PRIORITY = [
+  { key: 'mcp', path: '/mcp' },
+  { key: 'mcpServerCard', path: '/.well-known/mcp/server-card.json' },
+  { key: 'agentSkills', path: '/.well-known/agent-skills/index.json' },
+  { key: 'apiCatalog', path: '/.well-known/api-catalog' },
+  { key: 'swagger', path: '/swagger-ui' },
+];
+
+async function probeEndpoints(baseUrl, opts = {}) {
+  const cfg = { ...DEFAULTS, ...opts };
+  const relatedDomains = opts.relatedDomains || [];
+  const docsCandidates = opts.docsCandidates || [];
+  const allBases = [baseUrl, ...relatedDomains];
+
+  const signals = {};
+  const details = {};
+  const softFalse = [];
+  const blocked = [];
+  let timedOut = false;
+
+  const siteDeadline = Date.now() + cfg.siteBudgetMs;
+
+  // Build prioritized probe list
+  const probes = [];
+
+  // Priority 1: Exact docs candidates
+  for (const url of docsCandidates) {
+    const key = url.match(/api|swagger|openapi/i) ? 'apiDocs' : 'developerDocs';
+    probes.push({ key, url, priority: 1, isDocsCandidate: true });
+  }
+
+  // Priority 2-4: Standard probes across all base domains
+  for (const base of allBases) {
+    const b = base.replace(/\/+$/, '');
+    for (const p of MACHINE_READABLE) probes.push({ ...p, url: b + p.path, priority: 2 });
+    for (const p of HIGH_SIGNAL_DOCS) probes.push({ ...p, url: b + p.path, priority: 3 });
+    for (const p of AUTH_PROBES) probes.push({ ...p, url: b + p.path, priority: 3 });
+    for (const p of LOWER_PRIORITY) probes.push({ ...p, url: b + p.path, priority: 4 });
+  }
+
+  // Sort by priority
+  probes.sort((a, b) => a.priority - b.priority);
+
+  // Execute with bounded concurrency and site budget
+  let strongSignalFound = false;
+  const batchSize = cfg.maxConcurrencyPerSite;
+
+  for (let i = 0; i < probes.length; i += batchSize) {
+    if (Date.now() >= siteDeadline) { timedOut = true; break; }
+
+    // If we found strong docs candidates, skip lower-priority probes
+    if (strongSignalFound && probes[i].priority >= 4) break;
+
+    const batch = probes.slice(i, i + batchSize);
+    const remaining = siteDeadline - Date.now();
+    if (remaining <= 0) { timedOut = true; break; }
+
+    const batchTimeout = Math.min(remaining, cfg.perProbeTimeoutMs + 1000);
+    const batchResults = await Promise.allSettled(
+      batch.map(p => withTimeout(
+        probeUrlWithContent(p.url, cfg.perProbeTimeoutMs, cfg.maxSnippetBytes),
+        batchTimeout
+      ).then(r => ({ ...p, ...r })))
+    );
+
+    const followUpProbes = [];
+
+    for (const r of batchResults) {
+      if (r.status !== 'fulfilled') continue;
+      const probe = r.value;
+
+      if (probe.httpStatus >= 200 && probe.httpStatus < 400) {
+        const relevant = validateProbeContent(probe.key, probe.snippet, probe.contentType);
+        if (relevant) {
+          signals[probe.key] = true;
+          if (!details[probe.key]) details[probe.key] = [];
+          details[probe.key].push({ path: probe.url, status: probe.httpStatus, strength: relevant, isDocsCandidate: !!probe.isDocsCandidate });
+          if (relevant === 'strong' && probe.priority <= 2) strongSignalFound = true;
+
+          // Follow up to 2 high-signal links discovered in docs content
+          if (probe.isDocsCandidate && probe.snippet && followUpProbes.length < 4) {
+            const discovered = extractHighSignalLinks(probe.snippet, probe.url);
+            for (const link of discovered.slice(0, 2)) {
+              followUpProbes.push({ key: 'apiDocs', url: link, priority: 1, isDocsCandidate: true, isFollowUp: true });
+            }
+          }
+        } else {
+          // Even non-relevant pages may contain useful links (e.g., 404 pages listing related docs)
+          if (probe.isDocsCandidate && probe.snippet && followUpProbes.length < 4) {
+            const discovered = extractHighSignalLinks(probe.snippet, probe.url);
+            for (const link of discovered.slice(0, 2)) {
+              followUpProbes.push({ key: 'apiDocs', url: link, priority: 1, isDocsCandidate: true, isFollowUp: true });
+            }
+          }
+          const isJsShell = detectJsShell(probe.snippet, probe.contentType);
+          if (isJsShell) {
+            softFalse.push({ key: probe.key, path: probe.url, status: probe.httpStatus, reason: 'JS_RENDER_REQUIRED' });
+          } else {
+            softFalse.push({ key: probe.key, path: probe.url, status: probe.httpStatus, reason: 'content_not_relevant' });
+          }
+        }
+      } else if (probe.httpStatus === 403 || probe.httpStatus === 401) {
+        blocked.push({ key: probe.key, path: probe.url, status: probe.httpStatus, reason: 'blocked' });
+      } else if (probe.httpStatus === 999) {
+        blocked.push({ key: probe.key, path: probe.url, status: 999, reason: 'timeout' });
+      }
+    }
+
+    // Execute follow-up probes from discovered links (max 4, within site budget)
+    if (followUpProbes.length > 0 && Date.now() < siteDeadline) {
+      const remaining = siteDeadline - Date.now();
+      const fuResults = await Promise.allSettled(
+        followUpProbes.slice(0, 4).map(p => withTimeout(
+          probeUrlWithContent(p.url, cfg.perProbeTimeoutMs, cfg.maxSnippetBytes),
+          Math.min(remaining, cfg.perProbeTimeoutMs + 1000)
+        ).then(r => ({ ...p, ...r })))
+      );
+      for (const r of fuResults) {
+        if (r.status !== 'fulfilled') continue;
+        const probe = r.value;
+        if (probe.httpStatus >= 200 && probe.httpStatus < 400) {
+          const relevant = validateProbeContent(probe.key, probe.snippet, probe.contentType);
+          if (relevant) {
+            signals[probe.key] = true;
+            if (!details[probe.key]) details[probe.key] = [];
+            details[probe.key].push({ path: probe.url, status: probe.httpStatus, strength: relevant, isFollowUp: true });
+          }
+        }
+      }
+    }
+  }
+
+  // Score
+  let score = 0;
+  if (signals.openapi || signals.swagger) score += 25;
+  if (signals.apiDocs) score += 10;
+  if (signals.apiCatalog) score += 5;
+  if (signals.mcp || signals.mcpServerCard) score += 20;
+  if (signals.agentSkills) score += 5;
+  if (signals.developerDocs || signals.docs) score += 10;
+  if (signals.oauth || signals.oauthDiscovery) score += 10;
+  if (signals.authMd) score += 5;
+  if (signals.llmsTxt) score += 5;
+  if (signals.llmsTxtFull) score += 2;
+  score = Math.min(100, score);
+
+  const hasAnySignal = Object.values(signals).some(v => v);
+  const jsRenderRequired = softFalse.some(sf => sf.reason === 'JS_RENDER_REQUIRED');
+
+  let evidenceStatus = 'scored';
+  if (timedOut) evidenceStatus = 'timeout';
+  else if (!hasAnySignal && blocked.length > 5) evidenceStatus = 'evidence_unavailable';
+  else if (!hasAnySignal && jsRenderRequired) evidenceStatus = 'js_render_required';
+  else if (!hasAnySignal && blocked.length > 0) evidenceStatus = 'partial_evidence';
+
+  return { score, signals, details, softFalse, blocked, evidenceStatus, timedOut, jsRenderRequired, probeCount: probes.length, blockedCount: blocked.length };
+}
+
+function detectJsShell(snippet, contentType) {
+  if (!snippet || !contentType) return false;
+  if (!contentType.includes('html')) return false;
+  const s = snippet.toLowerCase();
+  // JS shell: has <script> but very little text content, or has __NEXT_DATA__ / react-root / app-root
+  const textContent = s.replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim();
+  const hasScripts = (s.match(/<script/g) || []).length;
+  const hasReactRoot = s.includes('__next') || s.includes('react-root') || s.includes('id="app"') || s.includes('id="root"');
+  if (hasScripts >= 2 && textContent.length < 200 && hasReactRoot) return true;
+  if (hasScripts >= 3 && textContent.length < 100) return true;
+  return false;
+}
+
+function validateProbeContent(key, snippet, contentType) {
+  if (!snippet || snippet.length < 5) return false;
+  const s = snippet.toLowerCase();
+  const ct = (contentType || '').toLowerCase();
+
+  switch (key) {
+    case 'openapi':
+      if (ct.includes('json') || ct.includes('yaml')) return (s.includes('"openapi"') || s.includes('"swagger"') || s.includes('"paths"') || s.includes('openapi:')) ? 'strong' : false;
+      return false;
+    case 'swagger':
+      if (ct.includes('json')) return s.includes('"swagger"') || s.includes('"paths"') ? 'strong' : false;
+      if (ct.includes('html')) return s.includes('swagger-ui') ? 'present' : false;
+      return false;
+    case 'apiDocs': {
+      const apiTerms = ['endpoint', 'api reference', 'authentication', 'request', 'response', 'sdk', 'webhook', 'rate limit', 'api key', 'curl', 'authorization', 'openapi', 'rest api'];
+      if (ct.includes('html') || ct.includes('markdown')) {
+        const hits = apiTerms.filter(t => s.includes(t)).length;
+        return hits >= 2 ? 'strong' : hits >= 1 ? 'present' : false;
+      }
+      if (ct.includes('json')) return s.includes('"endpoint') || s.includes('"paths"') ? 'strong' : false;
+      return false;
+    }
+    case 'apiCatalog':
+      if (ct.includes('json')) return s.includes('"apis"') ? 'strong' : false;
+      return false;
+    case 'mcp': case 'mcpServerCard':
+      if (ct.includes('json')) return (s.includes('"tools"') || s.includes('"resources"') || s.includes('"capabilities"')) ? 'strong' : false;
+      if (ct.includes('html')) return s.includes('model context protocol') || s.includes('mcp server') ? 'present' : false;
+      return false;
+    case 'agentSkills':
+      if (ct.includes('json')) return s.includes('"skills"') || s.includes('"actions"') ? 'strong' : false;
+      return false;
+    case 'developerDocs': case 'docs':
+      if (ct.includes('html') || ct.includes('markdown')) {
+        const terms = ['documentation', 'guide', 'reference', 'api', 'sdk', 'getting started', 'quickstart', 'install', 'authentication', 'endpoint', 'example', 'webhook', 'cli'];
+        const hits = terms.filter(t => s.includes(t)).length;
+        return hits >= 3 ? 'strong' : hits >= 1 ? 'present' : false;
+      }
+      return false;
+    case 'oauth': case 'oauthDiscovery':
+      if (ct.includes('json')) return (s.includes('authorization_endpoint') || s.includes('token_endpoint')) ? 'strong' : false;
+      if (ct.includes('html')) return (s.includes('oauth') || s.includes('authorize') || s.includes('client_id')) ? 'present' : false;
+      return false;
+    case 'authMd':
+      if (ct.includes('text') || ct.includes('markdown')) return (s.includes('auth') && s.length > 100) ? 'strong' : false;
+      if (ct.includes('html')) return false;
+      return false;
+    case 'llmsTxt': case 'llmsTxtFull':
+      if (ct.includes('html')) return false;
+      const lines = snippet.split('\n').filter(l => l.trim().length > 0);
+      return lines.length >= 3 ? 'strong' : lines.length >= 1 ? 'present' : false;
+    default:
+      return snippet.length > 50 ? 'present' : false;
+  }
+}
+
+function probeUrlWithContent(url, timeoutMs, maxBytes) {
+  return new Promise((resolve) => {
+    const mod = url.startsWith('https') ? https : http;
+    const req = mod.get(url, {
+      timeout: timeoutMs,
+      headers: { 'User-Agent': 'AvoreloBotReadinessCheck/1.0 (+https://avorelo.com/tools/agent-readiness)' },
+    }, (res) => {
+      // Follow redirects (max 3)
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        resolve({ httpStatus: res.statusCode, contentType: '', snippet: '', redirectedTo: res.headers.location });
+        return;
+      }
+      const contentType = res.headers['content-type'] || '';
+      let body = '';
+      let bytes = 0;
+      res.on('data', (chunk) => {
+        if (bytes < maxBytes) { body += chunk.toString('utf8').slice(0, maxBytes - bytes); bytes += chunk.length; }
+        if (bytes >= maxBytes) res.destroy();
+      });
+      res.on('end', () => resolve({ httpStatus: res.statusCode, contentType, snippet: body }));
+      res.on('error', () => resolve({ httpStatus: res.statusCode, contentType, snippet: body }));
+    });
+    req.on('error', () => resolve({ httpStatus: 999, contentType: '', snippet: '' }));
+    req.on('timeout', () => { req.destroy(); resolve({ httpStatus: 999, contentType: '', snippet: '' }); });
+  });
+}
+
+function extractHighSignalLinks(snippet, sourceUrl) {
+  const links = [];
+  const lower = snippet.toLowerCase();
+
+  // Extract absolute URLs that look like API/docs content
+  const absMatches = snippet.match(/https?:\/\/[^\s"'<>)]+/g) || [];
+  for (const l of absMatches) {
+    if (l.match(/rest-api|api-reference|openapi|swagger|authentication|webhook|endpoint/i) && !links.includes(l)) {
+      links.push(l);
+    }
+  }
+
+  // Extract relative links (markdown-style or bare paths) and make absolute
+  let baseUrl;
+  try { baseUrl = new URL(sourceUrl); } catch { return links; }
+  const relPatterns = [
+    /\(\/[^\s"'<>)]+\.md\)/g,
+    /\(\/docs\/[^\s"'<>)]+\)/g,
+    /href="(\/[^"]+)"/g,
+  ];
+  for (const pattern of relPatterns) {
+    const matches = snippet.matchAll(pattern);
+    for (const m of matches) {
+      const path = (m[1] || m[0]).replace(/[()]/g, '');
+      if (path.match(/rest-api|api-reference|authentication|webhook|endpoint/i)) {
+        const absUrl = baseUrl.origin + path;
+        if (!links.includes(absUrl)) links.push(absUrl);
+      }
+    }
+  }
+
+  return links.slice(0, 4);
+}
+
+function withTimeout(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise(resolve => setTimeout(() => resolve({ httpStatus: 999, contentType: '', snippet: '' }), ms)),
+  ]);
+}
+
+module.exports = { probeEndpoints, validateProbeContent, detectJsShell };

package/scripts/lib/external-readiness/external-readiness-runner.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+
+const PRIVATE_RANGES = [
+  /^10\./, /^172\.(1[6-9]|2\d|3[01])\./, /^192\.168\./, /^127\./,
+  /^0\./, /^169\.254\./, /^fc00:/i, /^fd/i, /^fe80:/i, /^::1$/,
+];
+
+function isPrivateIP(hostname) {
+  return PRIVATE_RANGES.some(re => re.test(hostname));
+}
+
+function normalizeUrl(raw) {
+  const trimmed = (raw || '').trim();
+  if (!trimmed) return { ok: false, error: 'URL is required.' };
+  let withProto = trimmed;
+  if (!/^https?:\/\//i.test(withProto)) withProto = 'https://' + withProto;
+  let parsed;
+  try { parsed = new URL(withProto); } catch { return { ok: false, error: 'Invalid URL.' }; }
+  if (!['http:', 'https:'].includes(parsed.protocol)) return { ok: false, error: 'Only http/https supported.' };
+  if (['localhost', '127.0.0.1', '::1'].includes(parsed.hostname)) {
+    return { ok: false, error: 'Localhost not allowed in public mode.' };
+  }
+  if (isPrivateIP(parsed.hostname)) return { ok: false, error: 'Private IPs not allowed.' };
+  return { ok: true, url: parsed.origin + parsed.pathname.replace(/\/+$/, '') };
+}
+
+function fetchUrl(url, timeoutMs = 15000) {
+  return new Promise((resolve, reject) => {
+    const mod = url.startsWith('https') ? https : http;
+    const req = mod.get(url, { headers: { 'User-Agent': 'AvoreloBotReadinessCheck/1.0' }, timeout: timeoutMs }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetchUrl(res.headers.location, timeoutMs).then(resolve, reject);
+      }
+      let body = '';
+      res.on('data', chunk => { body += chunk; if (body.length > 2_000_000) req.destroy(); });
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body }));
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('Timeout')); });
+  });
+}
+
+async function runReadiness(rawUrl, opts = {}) {
+  const norm = normalizeUrl(rawUrl);
+  if (!norm.ok) return { url: rawUrl, error: norm.error, findings: [], score: 0 };
+
+  const url = norm.url;
+  const findings = [];
+  const errors = [];
+
+  let html = '', headers = {};
+  try {
+    const page = await fetchUrl(url);
+    html = page.body;
+    headers = page.headers || {};
+    if (page.status >= 400) errors.push(`HTTP ${page.status}`);
+  } catch (err) {
+    return { url, error: err.message, findings: [], score: 0, errors: [err.message] };
+  }
+
+  // Metadata
+  const title = (html.match(/<title[^>]*>([\s\S]*?)<\/title>/i) || [])[1];
+  if (!title) findings.push({ id: 'meta-no-title', severity: 'blocking', title: 'Missing page title' });
+  const desc = html.match(/<meta\s+name=["']description["']\s+content=["']([^"']*)["']/i);
+  if (!desc) findings.push({ id: 'meta-no-description', severity: 'important', title: 'Missing meta description' });
+  if (!html.match(/<link[^>]*rel=["']canonical["']/i)) findings.push({ id: 'meta-no-canonical', severity: 'advisory', title: 'Missing canonical URL' });
+
+  // OG
+  if (!html.match(/<meta\s+property=["']og:title["']/i)) findings.push({ id: 'meta-no-og-title', severity: 'advisory', title: 'Missing og:title' });
+
+  // Schema
+  if (!html.match(/<script\s+type=["']application\/ld\+json["']/i)) {
+    findings.push({ id: 'schema-no-jsonld', severity: 'important', title: 'No JSON-LD structured data' });
+  }
+
+  // Robots/sitemap/llms with content snippets
+  const contentSnippets = { robotsTxt: null, sitemapXml: null, llmsTxt: null };
+  try {
+    const r = await fetchUrl(url + '/robots.txt', 8000);
+    if (r.status >= 400) findings.push({ id: 'crawl-no-robots', severity: 'advisory', title: 'No robots.txt' });
+    else contentSnippets.robotsTxt = r.body.slice(0, 8000);
+  } catch { findings.push({ id: 'crawl-no-robots', severity: 'advisory', title: 'No robots.txt' }); }
+
+  try {
+    const s = await fetchUrl(url + '/sitemap.xml', 8000);
+    if (s.status >= 400) findings.push({ id: 'crawl-no-sitemap', severity: 'advisory', title: 'No sitemap.xml' });
+    else contentSnippets.sitemapXml = s.body.slice(0, 8000);
+  } catch { findings.push({ id: 'crawl-no-sitemap', severity: 'advisory', title: 'No sitemap.xml' }); }
+
+  try {
+    const l = await fetchUrl(url + '/llms.txt', 8000);
+    if (l.status >= 400) findings.push({ id: 'docs-no-llms-txt', severity: 'advisory', title: 'No llms.txt' });
+    else contentSnippets.llmsTxt = l.body.slice(0, 8000);
+  } catch { findings.push({ id: 'docs-no-llms-txt', severity: 'advisory', title: 'No llms.txt' }); }
+
+  // Security headers
+  if (!headers['strict-transport-security']) findings.push({ id: 'sec-no-hsts', severity: 'important', title: 'Missing HSTS header' });
+  if (!headers['x-content-type-options']) findings.push({ id: 'sec-no-xcto', severity: 'advisory', title: 'Missing X-Content-Type-Options' });
+
+  const blocking = findings.filter(f => f.severity === 'blocking').length;
+  const important = findings.filter(f => f.severity === 'important').length;
+  const advisory = findings.filter(f => f.severity === 'advisory').length;
+  const score = Math.max(0, 100 - blocking * 25 - important * 10 - advisory * 3);
+
+  return { url, scannedAt: new Date().toISOString(), score, findings, errors, html, headers, contentSnippets };
+}
+
+module.exports = { runReadiness, normalizeUrl };

package/scripts/lib/external-readiness/full-agent-readiness-scorer.js

@@ -0,0 +1,220 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Full Agent Readiness: evidence-based, capped.
+ * No subscore can be 100 without measured evidence.
+ * Missing API/MCP/tool docs = cannot be strong.
+ * Missing runtime verification = handoff/UX capped.
+ * Missing live visibility = AI Visibility must be evidence-readiness only.
+ */
+
+// Weights calibrated against Ora layers (Discovery 20, Identity 20, Auth 30, Integration 20, UX 10)
+// Avorelo adds AEO evidence and manual visibility as separate surfaces
+const SURFACES = [
+  { id: 'discovery', label: 'Discovery', weight: 12, check: checkDiscovery },
+  { id: 'identity', label: 'Identity clarity', weight: 8, check: checkIdentity },
+  { id: 'auth', label: 'Auth & Access', weight: 15, check: checkAuth },
+  { id: 'agent_integration', label: 'Agent Integration (API/MCP)', weight: 22, check: checkAgentIntegration },
+  { id: 'agent_ux', label: 'Agent-Friendly UX', weight: 8, check: checkAgentUX },
+  { id: 'handoff', label: 'Handoff', weight: 7, check: checkHandoff },
+  { id: 'aeo_evidence', label: 'AI Visibility Readiness Signals', weight: 10, check: checkAeoEvidence },
+  { id: 'manual_visibility', label: 'Manual-Live Visibility', weight: 3, check: checkManualVisibility },
+];
+
+function scoreFullAgentReadiness(opts) {
+  const { html, headers, repoRoot, aeoEvidence, manualVisibility, externalImport, runtimeVerified, endpointProbe } = opts;
+  const results = [];
+  const findings = [];
+
+  for (const surface of SURFACES) {
+    const r = surface.check({ html, headers, repoRoot, aeoEvidence, manualVisibility, externalImport, runtimeVerified, endpointProbe });
+    results.push({ id: surface.id, label: surface.label, weight: surface.weight, score: r.score, evidenceBasis: r.evidenceBasis || 'estimated', ...r });
+    findings.push(...(r.findings || []));
+  }
+
+  const totalWeight = SURFACES.reduce((s, a) => s + a.weight, 0);
+  const scored = results.reduce((s, r) => s + (r.score / 100) * r.weight, 0);
+  const overall = Math.round((scored / totalWeight) * 100);
+  const level = overall >= 85 ? 'strong' : overall >= 65 ? 'good' : overall >= 40 ? 'needs work' : 'low';
+
+  return { overall, level, surfaces: results, findings };
+}
+
+function checkDiscovery({ html, aeoEvidence, manualVisibility }) {
+  const findings = [];
+  let score = 0;
+  let basis = 'estimated';
+
+  // Primary: AEO evidence readiness (deterministic)
+  if (aeoEvidence) {
+    score = Math.min(80, aeoEvidence.overall); // Capped at 80 without live evidence
+    basis = 'measured';
+  }
+
+  // Boost with manual-live data
+  if (manualVisibility?.measured) {
+    const mentionBoost = Math.min(20, Math.round(manualVisibility.summary.mentionRate / 5));
+    score = Math.min(100, score + mentionBoost);
+    basis = 'measured';
+  }
+
+  if (score < 30) {
+    findings.push({ id: 'far-low-discovery', category: 'full_agent_readiness', severity: 'blocking', confidence: basis, title: `Discovery weak (${score}/100)`, detail: 'AI systems may not find or recommend this product.', autoFixEligible: false, requiresApproval: false });
+  }
+
+  return { score, evidenceBasis: basis, findings };
+}
+
+function checkIdentity({ html }) {
+  let score = 0;
+  const findings = [];
+  const h = html || '';
+
+  if (h.match(/<title[^>]*>.{10,}<\/title>/i)) score += 25;
+  if (h.match(/<meta\s+name=["']description["']/i)) score += 20;
+  if (h.match(/application\/ld\+json/i)) score += 25;
+  if (h.match(/og:title/i) && h.match(/og:description/i)) score += 20;
+  // Cap: never 100 without measured evidence of what AI engines actually see
+  score = Math.min(90, score);
+
+  if (score < 50) {
+    findings.push({ id: 'far-weak-identity', category: 'full_agent_readiness', severity: 'important', title: 'Product identity not clear enough for agents', autoFixEligible: false, requiresApproval: false });
+  }
+  return { score, evidenceBasis: 'measured', findings };
+}
+
+function checkAuth({ html, repoRoot, endpointProbe }) {
+  let score = 0;
+  const findings = [];
+  const h = html || '';
+
+  // Basic auth surface from HTML
+  if (h.match(/login|sign.?in|sign.?up/i)) score += 15;
+  if (h.match(/google|github|discord|slack/i)) score += 10;
+
+  // Endpoint probe signals (much more valuable)
+  if (endpointProbe) {
+    if (endpointProbe.signals.oauth || endpointProbe.signals.oauthDiscovery) score += 25;
+    if (endpointProbe.signals.authMd) score += 20;
+  }
+
+  // Local source check
+  if (repoRoot && fs.existsSync(path.join(repoRoot, 'src', 'auth'))) score += 10;
+
+  if (score < 25) {
+    findings.push({ id: 'far-weak-auth', category: 'full_agent_readiness', severity: 'important', title: 'No agent-accessible auth surface', detail: 'No OAuth discovery, auth.md, or documented auth flow for agents.', autoFixEligible: false, requiresApproval: true });
+  }
+
+  score = Math.min(90, score);
+  return { score, evidenceBasis: endpointProbe ? 'measured' : 'estimated', findings };
+}
+
+function checkAgentIntegration({ html, repoRoot, endpointProbe }) {
+  let score = 0;
+  const findings = [];
+  const h = html || '';
+
+  let hasOpenAPI = false;
+  let hasMCP = false;
+  let hasDocs = false;
+
+  // Primary: use endpoint probe data (real HTTP probes)
+  if (endpointProbe) {
+    if (endpointProbe.signals.openapi || endpointProbe.signals.swagger) { score += 30; hasOpenAPI = true; }
+    if (endpointProbe.signals.apiDocs) { score += 10; hasDocs = true; }
+    if (endpointProbe.signals.mcp || endpointProbe.signals.mcpWellKnown) { score += 25; hasMCP = true; }
+    if (endpointProbe.signals.developerDocs || endpointProbe.signals.docs) { score += 10; hasDocs = true; }
+    if (endpointProbe.signals.oauth || endpointProbe.signals.oauthDocs) score += 10;
+    if (endpointProbe.signals.llmsTxt) score += 5;
+  } else {
+    // Fallback: HTML inspection + local file checks
+    if (h.match(/openapi|swagger|\/api\/docs/i)) { score += 20; hasOpenAPI = true; }
+    if (h.match(/mcp|model.context.protocol/i)) { score += 15; hasMCP = true; }
+    if (h.match(/sdk|npm install|npx/i)) score += 10;
+  }
+
+  // Local file checks
+  if (repoRoot) {
+    for (const c of ['openapi.json', 'openapi.yaml', 'swagger.json']) {
+      if (fs.existsSync(path.join(repoRoot, c))) { score += 10; hasOpenAPI = true; break; }
+    }
+    for (const c of ['mcp.json', '.mcp', 'docs/mcp']) {
+      if (fs.existsSync(path.join(repoRoot, c))) { score += 5; hasMCP = true; break; }
+    }
+    if (fs.existsSync(path.join(repoRoot, 'docs', 'INSTALL.md'))) score += 5;
+  }
+
+  if (!hasOpenAPI) {
+    findings.push({ id: 'far-no-openapi', category: 'full_agent_readiness', severity: 'important', title: 'No public API / OpenAPI spec', detail: 'Agents cannot discover or use APIs without documentation.', autoFixEligible: false, requiresApproval: true });
+  }
+  if (!hasMCP) {
+    findings.push({ id: 'far-no-mcp', category: 'full_agent_readiness', severity: 'important', title: 'No MCP readiness visible', detail: 'Agents using MCP cannot discover this product as a tool server.', autoFixEligible: false, requiresApproval: true });
+  }
+
+  // Hard cap: without API and MCP, max 25
+  if (!hasOpenAPI && !hasMCP) score = Math.min(score, 25);
+  // Without either: max 50
+  else if (!hasOpenAPI || !hasMCP) score = Math.min(score, 50);
+
+  return { score: Math.min(90, score), evidenceBasis: endpointProbe ? 'measured' : 'estimated', findings };
+}
+
+function checkAgentUX({ html, runtimeVerified }) {
+  let score = 0;
+  const findings = [];
+  const h = html || '';
+
+  if (h.match(/<button/i)) score += 20;
+  if (h.match(/<a\s+href/i)) score += 20;
+  if (h.match(/aria-label/i)) score += 20;
+  if (h.match(/npx|npm install/i)) score += 20;
+
+  // Cap without runtime verification
+  if (!runtimeVerified) {
+    score = Math.min(70, score);
+    findings.push({ id: 'far-ux-not-runtime-verified', category: 'full_agent_readiness', severity: 'advisory', confidence: 'estimated', title: 'Agent UX not runtime-verified', detail: 'Run Wasp/browser to verify the full interaction flow.', autoFixEligible: false, requiresApproval: false });
+  }
+
+  return { score: Math.min(90, score), evidenceBasis: runtimeVerified ? 'measured' : 'estimated', findings };
+}
+
+function checkHandoff({ html, runtimeVerified }) {
+  let score = 0;
+  const findings = [];
+  const h = html || '';
+
+  if (h.match(/<title/i) && h.match(/<meta\s+name=["']description["']/i)) score += 20;
+  if (h.match(/application\/ld\+json/i)) score += 20;
+  if (h.match(/npx|npm install/i)) score += 20;
+  if (h.match(/login|sign.?up/i)) score += 20;
+  if (h.match(/api|docs|sdk/i)) score += 20;
+
+  if (!runtimeVerified) score = Math.min(70, score);
+
+  return { score: Math.min(90, score), evidenceBasis: runtimeVerified ? 'measured' : 'estimated', findings };
+}
+
+function checkAeoEvidence({ aeoEvidence }) {
+  const findings = [];
+  if (!aeoEvidence) {
+    findings.push({ id: 'far-aeo-not-checked', category: 'full_agent_readiness', severity: 'advisory', title: 'AEO evidence readiness not checked', detail: 'Run with --aeo-readiness to measure.', autoFixEligible: false, requiresApproval: false });
+    return { score: 0, evidenceBasis: 'not_measured', findings };
+  }
+  return { score: Math.min(90, aeoEvidence.overall), evidenceBasis: 'measured', findings };
+}
+
+function checkManualVisibility({ manualVisibility }) {
+  const findings = [];
+  if (!manualVisibility?.measured) {
+    return { score: 0, evidenceBasis: 'not_provided', findings: [
+      { id: 'far-manual-not-provided', category: 'full_agent_readiness', severity: 'advisory', title: 'Manual-live AI visibility not provided', detail: 'Import manual results from ChatGPT/Gemini/Perplexity for live evidence.', autoFixEligible: false, requiresApproval: false }
+    ] };
+  }
+  const rate = manualVisibility.summary.mentionRate || 0;
+  return { score: Math.min(90, rate), evidenceBasis: 'measured', findings };
+}
+
+module.exports = { scoreFullAgentReadiness, SURFACES };